jsonforms-nuxt-ui-renderers

jsonforms-nuxt-ui-renderers

JSONForms renderer set for Nuxt UI (@nuxt/ui) on Vue 3 / Nuxt.

This package provides a renderers registry you pass to @jsonforms/vue's JsonForms component.

Install

pnpm add jsonforms-nuxt-ui-renderers @jsonforms/core @jsonforms/vue
pnpm add -D @nuxt/ui

Nuxt UI should be installed/configured in your Nuxt app (see Nuxt UI docs).

Usage (Nuxt / Vue)

import { JsonForms } from '@jsonforms/vue'
import { nuxtUiRenderers } from 'jsonforms-nuxt-ui-renderers'
import 'jsonforms-nuxt-ui-renderers/styles.css'

// <JsonForms :schema="schema" :uischema="uischema" :data="data" :renderers="nuxtUiRenderers" />

Import styles.css for default styling of layout panels, labels, and typography. The package uses semantic class names (jf-*) and does not depend on Tailwind or any specific CSS framework.

Important

• These renderers resolve Nuxt UI components by name (e.g. UFormField, UInput, UTextarea, USelectMenu, UFieldGroup, USwitch, UButton). Your app must register Nuxt UI components globally (Nuxt does this when you use the @nuxt/ui module).
• If you override component names or use a different UI library, these renderers will not work out of the box.

Supported UI schema / schema constructs

This package is intentionally small and opinionated: it ships a single renderer registry (nuxtUiRenderers) covering the following UI schema elements / JSON Schema patterns.

Controls (field types)

• String: JSON Schema type: "string" → UInput
• Multiline string: JSONForms “multiline” control (e.g. uischema.options.multi: true) → UTextarea
• Password: JSON Schema type: "string" + format: "password" → UInput type="password" with show/hide toggle button
• Number: JSON Schema type: "number" → native <input type="number"> inside UFormField (parses to number, empty becomes undefined). Native inputs are used so each input event updates JsonForms core immediately; UInput alone could leave parent :data stale in some form-field setups.
• Integer: JSON Schema type: "integer" → native <input type="number" inputmode="numeric" step="1"> (parses to integer, empty becomes undefined). Same rationale as number.
• Boolean: JSON Schema type: "boolean" → USwitch
• Enum (single-select): JSON Schema enum: [...] (or oneOf: [{ const, title? }, ...]) → UFieldGroup with buttons for 2–4 options, otherwise USelectMenu. Button-group layout stays LTR; set localeDirection: 'rtl' in createNuxtUiRenderers(...) to apply RTL direction to option labels.
• Enum (multi-select): JSON Schema type: "array" with items being an enum schema (supports $ref’d items) → USelectMenu multiple
• Nullable controls: unambiguous anyOf / oneOf schemas with one supported non-null variant and a null variant use the non-null control UI. A Clear action sets a non-null value to null and is hidden while the value is already null; a Null indicator makes the null state visible. An empty string ("") is a string value, not null, and remains clearable. Ambiguous unions are not guessed.

Layouts

• VerticalLayout
• HorizontalLayout (responsive: stacks on small screens, wraps into columns on larger screens)
• Group
• Label
• Categorization / Category

Complex types

• Arrays (list UI): any schema with type: "array" renders as a list with Add / Remove / Up / Down
  • Respects minItems / maxItems (disables buttons accordingly)
  • Item label can be customized via uischema.options.childLabelProp; otherwise it uses JSONForms’ first primitive property as a best-effort label
  • “Add” uses JSONForms createDefaultValue(...) for the item value
• Objects: object controls delegate to a detail UI schema
  • If no matching detail UI schema is registered, a default one is generated via JSONForms Generate.uiSchema(...)
  • The root object is rendered as a VerticalLayout; nested objects default to a Group using the control’s label

Theming

The package uses semantic class names (jf-*) for layout and typography. Two ways to customize:

Option 1: Default styles + CSS variables

Import the default stylesheet and override variables in your app:

import 'jsonforms-nuxt-ui-renderers/styles.css'

CSS variables (in styles.css) you can override in :root:

Option 2: Theme overrides (e.g. Tailwind)

Pass custom classes to match your app. You can omit styles.css when using full overrides:

import { createNuxtUiRenderers } from 'jsonforms-nuxt-ui-renderers'

const renderers = createNuxtUiRenderers({
  theme: {
    panel: 'rounded border border-default bg-muted/40 p-3',
    groupNested: 'rounded bg-muted/20 p-3',
    layoutVertical: 'flex flex-col gap-3',
    layoutHorizontal: 'flex flex-col gap-3 md:flex-row md:flex-wrap',
    labelSection: 'text-sm font-semibold',
    textMuted: 'text-sm text-muted',
    // ... see NuxtUiRenderersTheme for all keys
  },
})

Theme keys: panel, groupNested, layoutVertical, layoutVerticalWide, layoutHorizontal, layoutHorizontalItem, arrayItemToolbar, labelSection, labelSectionSpaced, textMuted, textMutedXs, textItemTitle, textItemSuffix, textLabel, flexBetween, flexBetweenStart, flexActions.

Contributing

• Install deps: pnpm install
• Run tests: pnpm test
• Build: pnpm build

Publishing (npm)

This repo is set up so you can publish via just publish (manual) or via GitHub Actions (recommended).

CI publish (recommended)

• Bump package.json version
• Push a tag matching the version: vX.Y.Z (e.g. v0.1.0)
• CI will run checks and publish to npm via npm “trusted publishing” (OIDC). No repository secret is required.

Manual publish (local)

• Ensure you are authenticated to npm (e.g. npm login or a preconfigured npm auth in your environment)
• Run:

just publish

Optional:

• NPM_TAG: publish under a dist-tag (e.g. next)

License

MIT