Skip to main content
Layouts control how form elements are arranged and grouped. JSON Forms provides several layout types to organize your forms effectively.

​
Vertical Layout

Stacks elements vertically, one below the other. 
{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Control",
      "label": "Name",
      "scope": "#/properties/name"
    },
    {
      "type": "Control",
      "label": "Birth Date",
      "scope": "#/properties/birthDate"
    }
  ]
}

​
Horizontal Layout

Arranges elements side by side in a row. 
{
  "type": "HorizontalLayout",
  "elements": [
    {
      "type": "Control",
      "label": "Name",
      "scope": "#/properties/name"
    },
    {
      "type": "Control",
      "label": "Birth Date",
      "scope": "#/properties/birthDate"
    }
  ]
}

​
Group Layout

Groups related elements together with a visual container and label. 
{
  "type": "Group",
  "label": "My Group",
  "elements": [
    {
      "type": "Control",
      "label": "Name",
      "scope": "#/properties/name"
    },
    {
      "type": "Control",
      "label": "Birth Date",
      "scope": "#/properties/birthDate"
    }
  ]
}

​
Nested Layouts

Combine multiple layout types to create complex form structures. 
{
  "type": "Group",
  "label": "My Group",
  "elements": [
    {
      "type": "HorizontalLayout",
      "elements": [
        {
          "type": "VerticalLayout",
          "elements": [
            {
              "type": "Control",
              "label": "Name",
              "scope": "#/properties/name"
            },
            {
              "type": "Control",
              "label": "Birth Date",
              "scope": "#/properties/birthDate"
            }
          ]
        },
        {
          "type": "VerticalLayout",
          "elements": [
            {
              "type": "Control",
              "label": "Name",
              "scope": "#/properties/name"
            },
            {
              "type": "Control",
              "label": "Birth Date",
              "scope": "#/properties/birthDate"
            }
          ]
        }
      ]
    }
  ]
}

​
Categorization

Create multi-step or tabbed forms with categorization. Each category becomes a separate tab or step. 
{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "minLength": 3,
      "description": "Please enter your first name"
    },
    "secondName": {
      "type": "string",
      "minLength": 3,
      "description": "Please enter your second name"
    },
    "birthDate": {
      "type": "string",
      "format": "date"
    },
    "nationality": {
      "type": "string",
      "enum": ["DE", "IT", "JP", "US", "RU", "Other"]
    },
    "provideAddress": {
      "type": "boolean"
    },
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "streetNumber": { "type": "string" },
        "city": { "type": "string" },
        "postalCode": { "type": "string", "maxLength": 5 }
      }
    }
  }
}

​
Layout Features

​
Label Element

Add descriptive text between form sections: 
{
  "type": "Label",
  "text": "Additional Information"
}

​
Conditional Categories

Use rules to show/hide categories based on form data: 
{
  "type": "Category",
  "label": "Address",
  "elements": [...],
  "rule": {
    "effect": "SHOW",
    "condition": {
      "scope": "#/properties/provideAddress",
      "schema": { "const": true }
    }
  }
}

​
Best Practices

  • Use VerticalLayout for forms with many fields or mobile-first designs
  • Use HorizontalLayout to group related fields that naturally fit together (e.g., first name and last name)
  • Use Group to visually separate sections of a long form
  • Use Categorization for multi-step wizards or complex forms with distinct sections
  • Nest layouts to create responsive, organized forms

​
Next Steps

  • Learn about Arrays for handling lists
  • Explore Complex Schemas for conditional logic and advanced patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us