Quickstart

Installation

Install as a community add-on using the Svelte CLI.

npm

npx sv add @sjsf

pnpm

pnpx sv add @sjsf

yarn

yarn dlx sv add @sjsf

bun

bunx sv add @sjsf

deno

deno x sv add @sjsf

Required peer dependencies: esm-env@1.2.0 svelte@5.34.8

Usage

Let’s start with the simplest setup:

Actions

<script lang="ts">
  import { theme } from "@sjsf/basic-theme";
  import { SimpleForm } from "@sjsf/form";
  import { createFormIdBuilder } from "@sjsf/form/id-builders/modern";
  import { createFormMerger } from "@sjsf/form/mergers/modern";
  import { resolver } from "@sjsf/form/resolvers/basic";
  import { translation } from "@sjsf/form/translations/en";
  import { createFormValidator } from "@sjsf/form/validators/noop";
</script>

<SimpleForm
  {theme}
  {translation}
  {resolver}
  schema={{
    type: "object",
    title: "Form title",
    properties: {
      text: {
        type: "string",
        title: "Text input",
      },
    },
    required: ["text"],
  }}
  merger={createFormMerger}
  idBuilder={createFormIdBuilder}
  validator={createFormValidator<{ text: string }>}
  onSubmit={(v) => window.alert(v.text)}
/>

In the example above, we create a form based on JSON Schema and use HTML5 validation to validate the form.

Although this is an extremely simple example, it turned out to be quite verbose, and here’s why:

• Explicit Configuration: The library favors explicit configuration over “magic” defaults.
• Tree-Shakeable Architecture: Each feature is located in its own submodule so you can import only the functionality you need, keeping your bundle lean and optimized.
• Highly Customizable: We provide extensive customization options so that you can tailor every aspect of the library to your needs.

Schema

Form options

UI Schema

With the uiSchema parameter you can customize the appearance of the form.

Note

We’ll talk about * as defaults in the Reusable defaults guide.

Basic Actions

<script lang="ts">
  import { type Schema, type UiSchemaRoot, SimpleForm } from "@sjsf/form";

  import * as defaults from "$lib/sjsf/defaults";

  const schema: Schema = {
    type: "string",
  };

  const uiSchema: UiSchemaRoot = {
    "ui:options": {
      title: "Custom title",
      help: "Help text",
      text: {
        placeholder: "placeholder",
      },
    },
  };
</script>

<SimpleForm
  {...defaults}
  {schema}
  {uiSchema}
  onSubmit={(v) => window.alert(v)}
/>

UI Schema

Form state

Use a factory to create a form to access its state.

Tip

Use getters to pass reactive parameters.

Basic Actions

<script lang="ts">
  import {
    BasicForm,
    createForm,
    getErrors,
    getValueSnapshot,
    type Schema,
  } from "@sjsf/form";

  import * as defaults from "$lib/sjsf/defaults";

  const schema: Schema = {
    type: "string",
    minLength: 10,
  };

  const form = createForm({
    ...defaults,
    initialValue: "initial",
    schema,
    onSubmit: console.log,
  });
</script>

<BasicForm {form} novalidate />

<pre>{JSON.stringify(
    { value: getValueSnapshot(form), errors: Array.from(getErrors(form)) },
    null,
    2
  )}</pre>

Form state

“Controlled” form

You can also specify the value option instead of the initialValue to access the internal state of the form.

Note

I believe that such use of the library should be limited, so here is a list of situations in which this approach can be used (if you doubt it, welcome to the discussions):

• Simultaneous editing of data from multiple locations (e.g., form + sidebar)

Caution

Before using, please read the section - Direct modification of form state

Basic Actions

<script lang="ts">
  import { BasicForm, createForm, type Schema } from "@sjsf/form";

  import * as defaults from "$lib/sjsf/defaults";

  const schema: Schema = {
    type: "string",
  };

  let value = $state("initial");

  const form = createForm<string>({
    ...defaults,
    schema,
    value: [() => value, (v) => (value = v)],
    onSubmit: console.log,
  });
</script>

<BasicForm {form} />

<pre>{JSON.stringify(value, null, 2)}</pre>