Key/Value Field Array

A shared form fragment for repeated text key/value pairs.

Loading...
import { zodResolver } from '@hookform/resolvers/zod'
import { useForm } from 'react-hook-form'
import { Button, Form_Shadcn_ } from 'ui'
import { FormItemLayout } from 'ui-patterns/form/FormItemLayout/FormItemLayout'
import { KeyValueFieldArray } from 'ui-patterns/form/KeyValueFieldArray/KeyValueFieldArray'
import { z } from 'zod'
 
const formSchema = z.object({
  headers: z.array(
    z.object({
      name: z.string(),
      value: z.string(),
    })
  ),
})
 
export function KeyValueFieldArrayDemo() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      headers: [{ name: 'x-client-info', value: 'studio-docs' }],
    },
  })
 
  function onSubmit(values: z.infer<typeof formSchema>) {
    console.log(values)
  }
 
  return (
    <Form_Shadcn_ {...form}>
      <form className="w-full max-w-2xl" onSubmit={form.handleSubmit(onSubmit)}>
        <FormItemLayout
          label="HTTP headers"
          description="Use KeyValueFieldArray for repeated text key/value pairs."
        >
          <KeyValueFieldArray
            control={form.control}
            name="headers"
            keyFieldName="name"
            valueFieldName="value"
            createEmptyRow={() => ({ name: '', value: '' })}
            keyPlaceholder="Header name"
            valuePlaceholder="Header value"
            addLabel="Add header"
            removeLabel="Remove header"
          />
        </FormItemLayout>
 
        <div className="mt-4">
          <Button size="tiny" type="primary" htmlType="submit">
            Submit
          </Button>
        </div>
      </form>
    </Form_Shadcn_>
  )
}

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'
<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.

When to use it

  • Use a plain 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.
PreviousStatus Codes
NextIntroduction