Types & Schema

Introduction

This document provides an overview of the key types used in Figma Forms. These types help define the structure and behavior of forms created with Figma Forms.

Installation

This package is a dependency of the parser and renderer packages, but you can also install it separately if needed:

npm install @uj-vilag/figma-forms-types

Core Types

JsonForm

Represents the overall structure of a form.

type JsonForm = {
  title: string;
  description: string;
  pages: JsonFormPage[];
};

JsonFormPage

Represents a single page within a form.

import { JsonSchema, VerticalLayout } from "@jsonforms/core";

type JsonFormPage = {
  id: string;
  title: string;
  description: string;
  schema: JsonFormSchema;
};

// schema and uischema
type JsonFormSchema = [JsonSchema, VerticalLayout];

Schema Structure

Figma Forms uses JSON Forms' dual-schema approach to separate data validation from UI presentation:

schema: Defines the data structure, types, and validation rules (JSON Schema)
uischema: Defines the UI layout, rendering, and component-specific options

Schema Example

The schema defines what data is collected and how it's validated:

schema.json

{
  "type": "object",
  "properties": {
    "501:4302": {
      "type": "string"
    }
  },
  "required": ["501:4302"]
}

UI Schema Example

The uischema defines how the form fields are rendered:

uischema.json

{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Control",
      "label": "Address",
      "scope": "#/properties/501:4302",
      "options": {
        "placeholder": "Enter your address",
        "id": "501:4302",
        "type": "text-field",
        "optional": false,
        "repeatable": false,
        "validation": "default",
        "width": "full"
      }
    }
  ]
}

See the JSON Forms documentation for more details on JsonSchema and VerticalLayout.

Control Options

The options field in the uischema control element provides additional configuration for the form fields. These options can be one of the following types:

Form element	Type
Label	`LabelOptions`
Text Field	`TextFieldOptions`
Number Field	`NumberFieldOptions`
Textarea	`TextareaOptions`
Section (fieldset)	`SectionOptions`
Dropdown	`DropdownOptions`
Radio Group	`RadioButtonGroupOptions`
Checkbox Group	`CheckboxGroupOptions`

Usage Example

Here's how these types are used when creating a custom renderer control:

textField.tsx

import type {
  ControlPropsOf,
  TextFieldOptions,
} from "@uj-vilag/figma-forms-types/jsonForms";
import { getWidthStyle } from "./helpers";
import { Feedback, Label, TextField } from "@uj-vilag/dap-components";

export default function TextFieldControl(props: ControlPropsOf<string>) {
  const { data, handleChange, path, label, uischema, id, errors } = props;
  const { optional, width, helperText, tipText, placeholder } =
    uischema.options as TextFieldOptions;

  const handleOnChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    // Update the form data when the input value changes
  };

  return (
    <Label
      labelText={label}
      helperText={helperText}
      requirement={optional ? "optional" : undefined}
      tipText={tipText}
      htmlFor={id}
    >
      <TextField
        id={id}
        value={data ?? ""}
        aria-describedby={`${id}-helperText ${id}-feedback`}
        onChange={handleOnChange}
        placeholder={placeholder}
        className="w-auto"
        style={getWidthStyle(width)}
        status={!!errors ? "error" : undefined}
      />
      <Feedback message={errors} id={`${id}-feedback`} />
    </Label>
  );
}

Types & Schema

On this page