GLUON / DOCS

@gluonjs/core / 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 ​

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 ​

changedProperties ​

Get Signature ​

get protected changedProperties(): ReadonlyMap<PropertyKey, unknown>

Returns the old values collected for the current update pass.

This is primarily a protected integration point for compatibility layers; native Gluon components should continue to use the lifecycle callbacks and reactive state directly.

Returns ​

ReadonlyMap<PropertyKey, unknown>

Inherited from ​

GluonElement.changedProperties

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 ​

Register and configure a schema-driven form-associated Custom Element through only the public package entry point:

ts
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);

Version-matched documentation. Examples are checked against the public package contracts.

Copyright © 2026 Marc Malerei