Field Array

FreeNew

A repeatable group of form rows with add, remove and keyboard reorder (Alt+Arrow), min and max limits, stable row keys, focus management and spoken announcements.

The full demo as documented.

Customize

Derived from this item’s props table, because it declares no controls of its own. Changes drive the preview live.

min` / `max1

itemName

children

Guide and examples

Installation


pnpm dlx shadcn@latest add https://ui.tealmac.com/r/field-array.json

Usage

import { FieldArray, FieldArrayRowActions } from "@/components/ui/field-array"

<FieldArray
  label="Phone numbers"
  itemName="phone"
  value={phones}
  onChange={setPhones}
  createItem={() => ({ label: "", number: "" })}
  min={1}
  max={4}
>
  {(row) => (
    <>
      <Input
        aria-label={`Number ${row.index + 1}`}
        value={row.item.number}
        onChange={(e) => row.update({ ...row.item, number: e.target.value })}
      />
      <FieldArrayRowActions />
    </>
  )}
</FieldArray>

It is controlled: keep the array in useState, in a form store (form.pushValue) or in React Hook Form (useFieldArray gives you the same value and setters).

Exports

Export	Description
`FieldArray`	The group: legend, rows, Add button, limits and the live region.
`FieldArrayRowActions`	Move up, move down and remove buttons for the current row.
`useFieldArrayRow()`	The row context (`item`, `index`, `id`, `remove`, `moveUp`, `moveDown`, `update`) for custom controls.

Props

Prop	Type	Default	Description
`value` / `onChange`	`T[]` / `(next: T[]) => void`	-	The array.
`createItem`	`() => T`	-	The new item for Add.
`min` / `max`	`number`	`0` / none	Remove is disabled at `min`; Add is disabled at `max`.
`label`	`ReactNode`	-	The legend.
`itemName`	`string`	`"item"`	Used in button names and announcements.
`children`	`(row) => ReactNode`	-	Renders one row.

Accessibility

The group is a fieldset with a legend; each row is a role="group" named "item 2 of 3".
Alt+ArrowUp and Alt+ArrowDown move the row that holds focus. The same actions exist as buttons, because a hidden shortcut cannot be the only way.
After add, remove or move, focus goes to the new row, the row that took the removed row's place, the moved row, or the Add button when nothing is left. A polite live region says what happened and the new count.
Move and remove buttons that cannot act (first row up, last row down, at min) are disabled but stay visible, so the row layout does not shift.

Testing

The component ships with a Testing Library test (field-array.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add https://ui.tealmac.com/r/field-array.json

Usage

import { FieldArray, FieldArrayRowActions } from "@/components/ui/field-array"

<FieldArray
  label="Phone numbers"
  itemName="phone"
  value={phones}
  onChange={setPhones}
  createItem={() => ({ label: "", number: "" })}
  min={1}
  max={4}
>
  {(row) => (
    <>
      <Input
        aria-label={`Number ${row.index + 1}`}
        value={row.item.number}
        onChange={(e) => row.update({ ...row.item, number: e.target.value })}
      />
      <FieldArrayRowActions />
    </>
  )}
</FieldArray>

It is controlled: keep the array in useState, in a form store (form.pushValue) or in React Hook Form (useFieldArray gives you the same value and setters).

Exports

Export	Description
`FieldArray`	The group: legend, rows, Add button, limits and the live region.
`FieldArrayRowActions`	Move up, move down and remove buttons for the current row.
`useFieldArrayRow()`	The row context (`item`, `index`, `id`, `remove`, `moveUp`, `moveDown`, `update`) for custom controls.

Props

Prop	Type	Default	Description
`value` / `onChange`	`T[]` / `(next: T[]) => void`	-	The array.
`createItem`	`() => T`	-	The new item for Add.
`min` / `max`	`number`	`0` / none	Remove is disabled at `min`; Add is disabled at `max`.
`label`	`ReactNode`	-	The legend.
`itemName`	`string`	`"item"`	Used in button names and announcements.
`children`	`(row) => ReactNode`	-	Renders one row.

Accessibility

The group is a fieldset with a legend; each row is a role="group" named "item 2 of 3".
Alt+ArrowUp and Alt+ArrowDown move the row that holds focus. The same actions exist as buttons, because a hidden shortcut cannot be the only way.
After add, remove or move, focus goes to the new row, the row that took the removed row's place, the moved row, or the Add button when nothing is left. A polite live region says what happened and the new count.
Move and remove buttons that cannot act (first row up, last row down, at min) are disabled but stay visible, so the row layout does not shift.

Testing

The component ships with a Testing Library test (field-array.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.