ArrayField

Form field component to handle array type values.

The ArrayField helps you to create complex forms with ease. It uses React Hook Forms useFieldArray internally.

Source
@saas-ui/forms
2.11.2 (latest)

Import

ArrayField: The wrapper component that composes the default ArrayField functionality.
ArrayFieldContainer: The container component provides context and state management.
ArrayFieldRows: Render prop component, to get access to the internal fields state. Must be a child of ArrayFieldContainer.
ArrayFieldRowContainer: The row container component providers row context.
ArrayFieldRowFields: Add the name prefix to the fields and acts as a horizontal form layout by default.
ArrayFieldAddButton: The default add button.
ArrayFieldRemoveButton: The default remove button.
useArrayFieldContext: A hook that returns the ArrayField internal state.
useArrayFieldRowContext: A hook that returns the ArrayFieldRowContainer state.
useArrayFieldAddButton: A hook that can be used to create a custom add button.
useArrayFieldRemoveButton: A hook that can be used to create a custom remove button.

import {
  ArrayField,
  ArrayFieldContainer,
  ArrayFieldRows,
  ArrayFieldRowContainer,
  ArrayFieldRowFields,
  ArrayFieldAddButton,
  ArrayFieldRemoveButton,
  useArrayFieldContext,
  useArrayFieldRowContext,
  useArrayFieldAddButton,
  useArrayFieldRemoveButton,
} from '@saas-ui/react'

Usage

Auto generated form

Simple array of string values.

function CreateTodoItem() {
  const schema = {
    title: {
      label: 'Title',
      rules: {
        required: true,
      },
    },
    todos: {
      type: 'array',
      min: 1,
      items: {
        type: 'object',
        properties: {
          todo: {
            label: 'Todo',
          },
        },
      },
    },
  }

  return (
    <Form
      defaultValues={{
        title: '',
        todos: [],
      }}
      schema={schema}
      onSubmit={() => null}
    />
  )
}

Basic object array

Field names inside an ArrayField need to be prefixed with array-field-name.$. The $ will be replaced with the index of the array item.

import { SubmitButton } from '@saas-ui/react'
import { Form } from '@saas-ui/forms/yup'

import * as yup from 'yup'

const issueSchema = yup.object().shape({
  title: yup.string().required().label('Title'),
})

const schema = issueSchema.concat(
  yup.object().shape({
    issues: yup.array().min(1).max(4).of(issueSchema),
  })
)

export default function CreateIssue() {
  return (
    <Form
      schema={schema}
      defaultValues={{
        title: '',
        issues: [{ title: '' }],
      }}
      onSubmit={() => Promise.resolve()}
    >
      {({ Field, ArrayField }) => (
        <FormLayout>
          <Field name="title" label="Title" />

          <ArrayField name="issues" label="Sub-issues">
            <Field name="issues.$.title" placeholder="Sub-issue title" />
          </ArrayField>

          <SubmitButton>Create todo</SubmitButton>
        </FormLayout>
      )}
    </Form>
  )
}

Complex array field

The array field can be fully composed to fit your specific use case.

import { SubmitButton } from '@saas-ui/react'
import { Form } from '@saas-ui/forms/yup'

import * as yup from 'yup'

const usersSchema = yup.object().shape({
  id: yup.string().required().label('Id'),
  name: yup.string().required().label('Name'),
  lastName: yup.string().required().label('Last name'),
})

const schema = yup.object().shape({
  users: yup.array().min(1).max(4).of(usersSchema),
})

export default function CustomArrayField() {
  return (
    <Form
      schema={schema}
      defaultValues={{
        users: [
          {
            id: '123',
            name: 'Eelco',
            lastName: 'Wiersma',
          },
        ],
      }}
      onSubmit={() => Promise.resolve()}
    >
      {({ Field }) => (
        <FormLayout>
          <ArrayFieldContainer
            name="users"
            label="Users"
            defaultValue={{}}
            keyName="key"
            min={2}
            max={4}
          >
            <ArrayFieldRows>
              {(fields) => (
                <>
                  {fields.map((field, i) => {
                    return (
                      <ArrayFieldRowContainer key={field.key} index={i}>
                        <ArrayFieldRowFields columns={3} spacing={1}>
                          <Field name="users.$.id" placeholder="Id" />
                          <Field name="users.$.name" placeholder="Name" />
                          <Box>
                            <Field
                              name={`users.${i}.lastName`}
                              placeholder="Last name"
                            />
                          </Box>
                        </ArrayFieldRowFields>
                        <ArrayFieldRemoveButton />
                      </ArrayFieldRowContainer>
                    )
                  })}
                </>
              )}
            </ArrayFieldRows>
            <ArrayFieldAddButton />
          </ArrayFieldContainer>

          <SubmitButton label="Submit" />
        </FormLayout>
      )}
    </Form>
  )
}

Custom buttons

Use the useArrayFieldContext and useArrayFieldRowContext hooks to interact with the ArrayFieldContainer and create advanced custom components.

The useArrayFieldAddButton and useArrayFieldRemoveButton hooks can be used to create custom buttons.

import { Button } from '@saas-ui/react'
import {
  useArrayFieldContext,
  useArrayFieldAddButton,
  useArrayFieldRemoveButton,
} from '@saas-ui/react'

const SimpleAddButton = () => {
  return <Button {...useArrayFieldAddButton()}>Add record</Button>
}

const CustomAddButton = () => {
  const { append, defaultValue, max, fields } = useArrayFieldContext()

  const isDisabled = !!(max && fields.length >= max)

  return (
    <Button
      onClick={() =>
        append(defaultValue, {
          shouldFocus: true,
          focusName: `arrayField.${fields.length}.id`,
        })
      }
      isDisabled={isDisabled}
    >
      Add record
    </Button>
  )
}

const RemoveButton = () => {
  return (
    <Button variant="ghost" {...useArrayFieldRemoveButton()}>
      Remove
    </Button>
  )
}

Accessing the ArrayField context

You can access the ArrayField context by using a ref, or using useArrayFieldContext

import { Button } from '@chakra-ui/react'
import { SubmitButton } from '@saas-ui/react'
import { Form } from '@saas-ui/forms/yup'

import * as yup from 'yup'

const issueSchema = yup.object().shape({
  title: yup.string().required().label('Title'),
})

const schema = issueSchema.concat(
  yup.object().shape({
    issues: yup.array().min(1).max(4).of(issueSchema),
  })
)

export default function CreateIssue() {
  const ref = React.useRef(null)

  return (
    <Form
      defaultValues={{
        title: '',
        issues: [{ title: '' }],
      }}
      onSubmit={() => Promise.resolve()}
    >
      {({ Field, ArrayField }) => (
        <FormLayout>
          <Field name="title" label="Title" />

          <ArrayField name="issues" label="Sub-issues" ref={ref}>
            <Field name="issues.$.title" placeholder="Sub-issue title" />
          </ArrayField>

          <Button
            onClick={() =>
              ref.current.append({ title: 'Appended using the ref api' })
            }
          >
            Add todo
          </Button>
          <SubmitButton>Create todo</SubmitButton>
        </FormLayout>
      )}
    </Form>
  )
}

Was this helpful?