@gluonjs/json-forms / packages/json-forms/src / JsonFormsElement

Class: JsonFormsElement

A form-associated Custom Element that renders the supported object, nested object, and bounded array JSON Forms subset through native controls.

Extends

GluonElement<JsonFormsEvents>

Constructors

Constructor

new JsonFormsElement(): JsonFormsElement

Creates the render root, finalizes declarations, captures pre-upgrade values, and applies defaults.

Returns

JsonFormsElement

Inherited from

GluonElement.constructor

Properties

data

data: JsonObject

disabled

disabled: boolean

messages

messages: JsonFormsMessageProvider | JsonFormsMessageProviderOptions | undefined

readOnly

readOnly: boolean

rendererRegistry

rendererRegistry: JsonFormsRendererRegistry | undefined

renderRoot

protected readonly renderRoot: ShadowRoot

Shadow root rendered by update; override createRenderRoot to customize it.

Inherited from

GluonElement.renderRoot

schema

schema: JsonSchema

uischema

uischema: JsonFormsUiSchema | undefined

events

readonly static events: object

Declares native output events and their propagation, cancellation, and validation rules.

change

change: object = {}

validation-change

validation-change: object = {}

Overrides

GluonElement.events

formAssociated

readonly static formAssociated: true = true

properties

readonly static properties: object

Declares reactive inputs and their attribute conversion, reflection, and validation rules.

data

data: object

data.attribute

attribute: false = false

data.default

default: () => JsonObject

Returns

JsonObject

data.validate

validate: (value) => true | "data must be a JSON object"

Parameters

value

unknown

Returns

true | "data must be a JSON object"

disabled

disabled: object

disabled.default

default: false = false

disabled.reflect

reflect: true = true

disabled.type

type: BooleanConstructor = Boolean

messages

messages: object

messages.attribute

attribute: false = false

messages.validate

validate: (value) => true | "messages must be a JSON Forms message provider or provider options"

Parameters

value

unknown

Returns

true | "messages must be a JSON Forms message provider or provider options"

readOnly

readOnly: object

readOnly.attribute

attribute: string = 'readonly'

readOnly.default

default: false = false

readOnly.reflect

reflect: true = true

readOnly.type

type: BooleanConstructor = Boolean

rendererRegistry

rendererRegistry: object

rendererRegistry.attribute

attribute: false = false

rendererRegistry.validate

validate: (value) => true | "rendererRegistry must be created with createJsonFormsRendererRegistry()"

Parameters

value

unknown

Returns

true | "rendererRegistry must be created with createJsonFormsRendererRegistry()"

schema

schema: object

schema.attribute

attribute: false = false

schema.default

default: () => JsonSchema

Returns

JsonSchema

schema.validate

validate: (value) => true | "schema must be a JSON Schema object"

Parameters

value

unknown

Returns

true | "schema must be a JSON Schema object"

uischema

uischema: object

uischema.attribute

attribute: false = false

uischema.validate

validate: (value) => true | "uischema must be a JSON Forms UI schema"

Parameters

value

unknown

Returns

true | "uischema must be a JSON Forms UI schema"

Overrides

GluonElement.properties

shadowRootRegistry?

readonly static optional shadowRootRegistry?: GluonElementRegistry

Optional explicit registry associated with this element's ShadowRoot.

Inherited from

GluonElement.shadowRootRegistry

slots

readonly static slots: SlotDeclarations = {}

Declares required named/default slots and whether the template supplies fallback content.

Inherited from

GluonElement.slots

styles

readonly static styles: CSSStyleSheet = jsonFormsStyles

Lists constructable stylesheets adopted into each instance's render root.

Overrides

GluonElement.styles

Accessors

errors

Get Signature

get errors(): readonly JsonFormValidationError[]

Returns

readonly JsonFormValidationError[]

form

Get Signature

get form(): HTMLFormElement | null

Returns

HTMLFormElement | null

labels

Get Signature

get labels(): NodeList

Returns

NodeList

name

Get Signature

get name(): string

Returns

string

Set Signature

set name(value): void

Parameters

value

string

Returns

void

type

Get Signature

get type(): string

Returns

string

updateComplete

Get Signature

get updateComplete(): Promise<void>

Resolves after the currently scheduled render and its update hooks finish.

Returns

Promise<void>

Inherited from

GluonElement.updateComplete

validationMessage

Get Signature

get validationMessage(): string

Returns

string

validity

Get Signature

get validity(): ValidityState | undefined

Returns

ValidityState | undefined

value

Get Signature

get value(): string

Returns

string

Set Signature

set value(value): void

Parameters

value

string

Returns

void

willValidate

Get Signature

get willValidate(): boolean

Returns

boolean

observedAttributes

Get Signature

get static observedAttributes(): string[]

Attribute names derived from properties; managed by Gluon for the Custom Elements platform.

Returns

string[]

Inherited from

GluonElement.observedAttributes

Methods

attributeChangedCallback()

attributeChangedCallback(name, oldValue, value): void

Converts a changed declared attribute and writes the corresponding property.

Parameters

name

string

oldValue

string | null

value

string | null

Returns

void

Inherited from

GluonElement.attributeChangedCallback

beginHydration()

beginHydration(): void

Defers the first connection render while official hydration binds declarative Shadow DOM.

Returns

void

Inherited from

GluonElement.beginHydration

checkValidity()

checkValidity(): boolean

Returns

boolean

connectedCallback()

connectedCallback(): void

Starts connection-owned reactivity and queues the first render. Prefer onConnected in subclasses.

Returns

void

Inherited from

GluonElement.connectedCallback

createRenderRoot()

protected createRenderRoot(): ShadowRoot

Creates the component render root. Override only when the default open ShadowRoot is unsuitable.

Returns

ShadowRoot

Inherited from

GluonElement.createRenderRoot

disconnectedCallback()

disconnectedCallback(): void

Stops connection-owned work and suspends rendering. Prefer onDisconnected in subclasses.

Returns

void

Inherited from

GluonElement.disconnectedCallback

emit()

protected emit<Name>(type, detail, init?): boolean

Dispatches a typed native CustomEvent using the matching static event declaration.

Events bubble and cross the Shadow DOM boundary by default. The return value is false only when a cancelable event was canceled by a listener.

Type Parameters

Name

Name extends "change" | "validation-change"

Parameters

type

Name

detail

JsonFormsEvents[Name]

init?

Omit<CustomEventInit<Events[Name]>, "detail"> = {}

Returns

boolean

Inherited from

GluonElement.emit

endHydration()

endHydration(): void

Resumes connection rendering after official hydration installs the hydrated root.

Returns

void

Inherited from

GluonElement.endHydration

expose()

protected expose<Public>(value): Readonly<Public>

Publishes a frozen, deliberately small public object for use with exposedRef().

Type Parameters

Public

Public extends object

Parameters

value

Public

Returns

Readonly<Public>

Inherited from

GluonElement.expose

focus()

focus(options?): void

MDN Reference

Parameters

options?

FocusOptions

Returns

void

Overrides

GluonElement.focus

formDisabledCallback()

formDisabledCallback(disabled): void

Parameters

disabled

boolean

Returns

void

formResetCallback()

formResetCallback(): void

Returns

void

formStateRestoreCallback()

formStateRestoreCallback(state): void

Parameters

state

string | File | FormData | null

Returns

void

onBeforeUpdate()

protected onBeforeUpdate(callback): void

Runs a callback before every update after the first render.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onBeforeUpdate

onConnected()

protected onConnected(callback): void

Runs a callback once after the first render of each connection.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onConnected

onDisconnected()

protected onDisconnected(callback): void

Runs a callback during disconnection after scoped reactive cleanup and render suspension.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onDisconnected

onErrorCaptured()

protected onErrorCaptured(callback): void

Captures descendant component errors; return true to stop propagation to outer boundaries.

Parameters

callback

ComponentErrorBoundary

Returns

void

Inherited from

GluonElement.onErrorCaptured

onUpdated()

protected onUpdated(callback): void

Runs a callback after every successful render, including the first render.

Parameters

callback

ComponentLifecycleCallback

Returns

void

Inherited from

GluonElement.onUpdated

render()

protected render(): TemplateResult

Returns the template for the current component state.

Returns

TemplateResult

Overrides

GluonElement.render

renderForServer()

renderForServer(): TemplateResult

Returns the component template without browser connection lifecycle for official server rendering.

Returns

TemplateResult

Inherited from

GluonElement.renderForServer

reportValidity()

reportValidity(): boolean

Returns

boolean

requestHotUpdate()

requestHotUpdate(): Promise<void>

Requests a render pass after the official Vite runtime patches compatible logic. Application code should use normal reactive or property updates.

Returns

Promise<void>

Inherited from

GluonElement.requestHotUpdate

requestUpdate()

protected requestUpdate(): Promise<void>

Schedules a deduplicated render and returns the same completion promise exposed by updateComplete.

Returns

Promise<void>

Inherited from

GluonElement.requestUpdate

setupConnection()

protected setupConnection(): void

Initializes work once per connection inside the connection's reactive effect scope.

Returns

void

Inherited from

GluonElement.setupConnection

teardownConnection()

protected teardownConnection(): void

Releases connection-local references after scoped cleanup and disconnect hooks.

Returns

void

Inherited from

GluonElement.teardownConnection

update()

protected update(): void

Commits the value returned by render into renderRoot.

Returns

void

Overrides

GluonElement.update

Example

import {
  createJsonFormsMessageProvider,
  createJsonFormsRendererRegistry,
  isJsonFormsRendererRegistry,
  JsonForm,
  JsonSchemaResolutionError,
  jsonFormsTag,
  registerJsonForms,
  resolveJsonSchema,
  type JsonFormChangeDetail,
  type JsonFormField,
  type JsonFormOptions,
  type JsonFormsElement,
  type JsonFormsMessageOverrides,
  type JsonFormsMessageProvider,
  type JsonFormsMessageProviderOptions,
  type JsonFormsRendererContext,
  type JsonFormsRendererControl,
  type JsonFormsRendererKind,
  type JsonFormsRendererRegistration,
  type JsonFormsRendererSelector,
  type JsonFormsUiSchema,
  type JsonFormValidationChangeDetail,
  type JsonFormValidationError,
  type JsonObject,
  type JsonSchema,
  type JsonSchemaResolutionOptions,
  type JsonValue,
} from '@gluonjs/json-forms';

const schema = { type: 'object', properties: { email: { $ref: '#/$defs/email' }, delivery: { type: 'string', enum: ['morning', 'afternoon'] } }, required: ['email'], $defs: { email: { type: 'string', format: 'email' } } } satisfies JsonSchema;
const referenceOptions = { maxDepth: 8, maxNodes: 64 } satisfies JsonSchemaResolutionOptions;
const resolvedSchema = resolveJsonSchema(schema, referenceOptions);
const referenceError = new JsonSchemaResolutionError('ref-pointer', 'Invalid reference.');
const uischema = { type: 'VerticalLayout', elements: [{ type: 'Control', scope: '#/properties/email', label: 'Email address' }, { type: 'Control', scope: '#/properties/delivery' }] } satisfies JsonFormsUiSchema;
const data = { email: 'hello@example.test', delivery: 'morning' } satisfies JsonObject;
const value: JsonValue = data.delivery;
const errors: readonly JsonFormValidationError[] = [];
const change: JsonFormChangeDetail = { data, errors };
const validation: JsonFormValidationChangeDetail = { valid: true, errors };
const messageOverrides = { selectPlaceholder: (required: boolean) => required ? 'Choose one' : 'No selection' } satisfies JsonFormsMessageOverrides;
const messageOptions = { locale: 'en-GB', messages: messageOverrides } satisfies JsonFormsMessageProviderOptions;
const messages: JsonFormsMessageProvider = createJsonFormsMessageProvider(messageOptions);
const rendererKind: JsonFormsRendererKind = 'select';
const rendererSelector = { kind: rendererKind, path: ['delivery'] } satisfies JsonFormsRendererSelector;
const rendererRegistration = { id: 'delivery-summary', selector: rendererSelector, priority: 10, render: (context: JsonFormsRendererContext) => String(context.value ?? '') } satisfies JsonFormsRendererRegistration;
const rendererRegistry = createJsonFormsRendererRegistry([rendererRegistration]);

registerJsonForms();
const element = document.createElement(jsonFormsTag) as JsonFormsElement;
element.schema = schema;
element.uischema = uischema;
element.data = data;
element.messages = messages;
element.rendererRegistry = rendererRegistry;
const rendererControl: JsonFormsRendererControl | undefined = undefined;
const field: JsonFormField | undefined = undefined;
const options = { schema, uischema, data, messages, rendererRegistry, onChange: (event) => console.log(event.detail.data), onValidationChange: (event) => console.log(event.detail.valid) } satisfies JsonFormOptions;
const view = JsonForm(options);
console.log(element.value, value, change, validation, isJsonFormsRendererRegistry(rendererRegistry), rendererControl, field, view, resolvedSchema, referenceError.keyword);