Skip to main content
Arrays in JSON Forms allow you to manage lists of items dynamically. Users can add, remove, and reorder items in the array.

​
Basic Array

A simple array of objects with multiple properties. 
{
  "type": "object",
  "properties": {
    "comments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "message": {
            "type": "string",
            "maxLength": 5
          },
          "enum": {
            "type": "string",
            "const": "foo"
          },
          "oneOfEnum": {
            "type": "string",
            "oneOf": [
              { "const": "foo" },
              { "const": "bar" }
            ]
          }
        }
      }
    },
    "foo": {
      "type": "string"
    }
  }
}

​
Array with Sorting

Enable sort buttons to allow users to reorder array items. 
{
  "type": "VerticalLayout",
  "elements": [
    {
      "type": "Control",
      "scope": "#/properties/comments",
      "options": {
        "showSortButtons": true
      }
    }
  ]
}

​
Nested Arrays

Arrays can contain objects with their own nested arrays, creating complex data structures. 
{
  "definitions": {
    "choicesContainer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "choices": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "type": "object",
  "properties": {
    "exampleArray": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/choicesContainer"
      }
    }
  }
}

​
Custom UI Schema for Nested Arrays

You can register custom UI schemas for array items to control how nested elements are rendered: 
import { rankWith, schemaMatches } from '@jsonforms/core';

const nestedArrayTester = rankWith(
  5,
  schemaMatches(
    (schema) => schema.$ref === '#/definitions/choicesContainer'
  )
);

const nestedArrayUISchema = {
  type: 'VerticalLayout',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/name'
    },
    {
      type: 'Control',
      scope: '#/properties/choices'
    }
  ]
};

const uischemas = [
  {
    tester: nestedArrayTester,
    uischema: nestedArrayUISchema
  }
];
Then pass the uischemas array to the JsonForms component.

​
Array Options

Customize array behavior with control options:

​
showSortButtons

Enable or disable sorting controls: 
{
  "type": "Control",
  "scope": "#/properties/comments",
  "options": {
    "showSortButtons": true
  }
}

​
detail

Customize the layout for each array item: 
{
  "type": "Control",
  "scope": "#/properties/comments",
  "options": {
    "detail": {
      "type": "VerticalLayout",
      "elements": [
        {
          "type": "Control",
          "scope": "#/properties/date"
        },
        {
          "type": "Control",
          "scope": "#/properties/message"
        }
      ]
    }
  }
}

​
elementLabelProp

Specify which property to use as the label for array items: 
{
  "type": "Control",
  "scope": "#/properties/comments",
  "options": {
    "elementLabelProp": "message"
  }
}

​
List with Detail

For complex array items, use the ListWithDetail renderer to show a master-detail view: 
{
  "type": "ListWithDetail",
  "scope": "#/properties/comments",
  "options": {
    "labelRef": "#/items/properties/message",
    "detail": {
      "type": "VerticalLayout",
      "elements": [
        {
          "type": "Control",
          "scope": "#/properties/date"
        },
        {
          "type": "Control",
          "scope": "#/properties/message"
        }
      ]
    }
  }
}

​
Array Validation

JSON Schema provides validation constraints for arrays: 
{
  "type": "array",
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true,
  "items": {
    "type": "string"
  }
}
  • minItems: Minimum number of items required
  • maxItems: Maximum number of items allowed
  • uniqueItems: Whether all items must be unique

​
Best Practices

  • Use showSortButtons when the order of items matters
  • Provide elementLabelProp to make arrays more user-friendly
  • Use ListWithDetail for arrays with complex objects
  • Set minItems and maxItems to guide users on expected array sizes
  • For deeply nested arrays, consider registering custom UI schemas for better control

​
Next Steps

  • Explore Complex Schemas for oneOf, anyOf, and conditional logic
  • Learn about Rules for dynamic form behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us