Key/Value Field Array

<ComponentPreview name="key-value-field-array-demo" description="A shared form fragment for repeated text key/value pairs." peekCode showDottedGrid wide />

Usage

Use KeyValueFieldArray when each row is two text inputs backed by react-hook-form, such as HTTP headers, query parameters, or configuration parameters.

import { KeyValueFieldArray } from 'ui-patterns/form/KeyValueFieldArray/KeyValueFieldArray'
import { getKeyValueFieldArrayValidationIssues } from 'ui-patterns/form/KeyValueFieldArray/validation'

<KeyValueFieldArray
  control={form.control}
  name="headers"
  keyFieldName="name"
  valueFieldName="value"
  createEmptyRow={() => ({ name: '', value: '' })}
  keyPlaceholder="Header name"
  valuePlaceholder="Header value"
  addLabel="Add header"
/>

KeyValueFieldArray owns the row add/remove behavior and renders the per-input form messages for you. Compose it inside FormItemLayout when you want the standard label, description, and message treatment around the entire section.

Validation

KeyValueFieldArray is rendering-only. Keep validation in the consumer schema and use the shared validation helper when you want the standard draft-row behaviour:

• fully empty rows may remain drafts
• partially filled rows should show inline errors on the missing cell

If you persist the array rows directly, strip fully empty draft rows before saving them.

const formSchema = z
  .object({
    headers: z.array(z.object({ name: z.string().trim(), value: z.string().trim() })),
  })
  .superRefine((data, ctx) => {
    getKeyValueFieldArrayValidationIssues({
      rows: data.headers,
      keyFieldName: 'name',
      valueFieldName: 'value',
      keyRequiredMessage: 'Header name is required',
      valueRequiredMessage: 'Header value is required',
    }).forEach((issue) => {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: issue.message,
        path: ['headers', ...issue.path],
      })
    })
  })

When to use it

• Use Single Value Field Array for repeated single values such as redirect URIs.
• Use KeyValueFieldArray for repeated text/text pairs such as headers, parameters, and config entries.
• Build a custom row UI instead when each row mixes different controls, such as a text input paired with a Select.