Form

Create fully functional React forms with just a few lines of code.

The Form component is an abstraction around React Hook Form and follows the WAI specifications for forms.

Import#

Form: The wrapper component provides context, state, and focus management.
FormLayout: Create consistent field spacing and positioning.
Field: Renders a fully functional form control, supports multiple types. Must be a child of Form.
DisplayIf: Conditionally render parts of a form.
SubmitButton: A button with type submit and default color scheme primary and isLoading state when the form is submitting.

import {
  Form,
  FormLayout,
  Field,
  DisplayIf,
  SubmitButton,
} from '@saas-ui/react'

Best practises#

Do
Keep optional fields to a minimum.
Make it clear which fields are required or optional.
Group related information in sections to make forms easier to scan.
Consider splitting up long forms into multiple steps.
Position the submit button consistenly throughout all forms.

Don't
Use too many ungrouped fields on a single page.
Use tabs inside forms.

Usage#

Basic form#

import { Form, Field, FormLayout, SubmitButton } from '@saas-ui/react'

export default function BasicForm() {
  const onSubmit = (params) => {
    console.log(params)
    return new Promise((resolve) => {
      setTimeout(resolve, 1000)
    })
  }

  return (
    <Form
      defaultValues={{
        name: 'Saas UI',
        description: '',
      }}
      onSubmit={onSubmit}
    >
      <FormLayout>
        <Field
          name="name"
          label="Name"
          type="text"
          help="Choose a name for this project"
          rules={{ required: true }}
        />

        <Field
          name="description"
          type="textarea"
          label="Description"
          placeholder="Optional description"
        />

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

Typed form#

Form accepts a render props, which gives you access to the internal form state, but also to the Field component. This allows you create typesafe forms, the name property of Field is typed based on the defaultValues prop.

import { Form, FormLayout, SubmitButton } from '@saas-ui/react'

export default function BasicForm() {
  const onSubmit = (params) => {
    console.log(params)
    return new Promise((resolve) => {
      setTimeout(resolve, 1000)
    })
  }

  return (
    <Form
      defaultValues={{
        name: 'Saas UI',
        description: '',
      }}
      onSubmit={onSubmit}
    >
      {({ Field }) => (
        <FormLayout>
          <Field
            name="name"
            label="Name"
            type="text"
            help="Choose a name for this project"
            rules={{ required: true }}
          />

          <Field
            name="description"
            type="textarea"
            label="Description"
            placeholder="Optional description"
          />

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

Zod form#

If you are using Zod, you can use the Form component from @saas-ui/forms/zod which accepts a schema prop. The Field component will be typed based on the schema.

import { Form } from '@saas-ui/forms/zod'
import { FormLayout, SubmitButton } from '@saas-ui/react'
import * as z from 'zod'

const schema = z.object({
  name: z.string().nonempty('Name is required'),
  description: z.string().optional(),
})

export default function BasicForm() {
  const onSubmit = (params) => {
    console.log(params)
    return new Promise((resolve) => {
      setTimeout(resolve, 1000)
    })
  }

  return (
    <Form
      schema={schema}
      defaultValues={{
        name: 'Saas UI',
        description: '',
      }}
      onSubmit={onSubmit}
    >
      {({ Field }) => (
        <FormLayout>
          <Field
            name="name"
            label="Name"
            type="text"
            help="Choose a name for this project"
            rules={{ required: true }}
          />

          <Field
            name="description"
            type="textarea"
            label="Description"
            placeholder="Optional description"
          />

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

Yup form#

If you are using Yup, you can use the Form component from @saas-ui/forms/yup which accepts a schema prop. The Field component will be typed based on the schema.

import { Form } from '@saas-ui/forms/yup'
import { FormLayout, SubmitButton } from '@saas-ui/react'
import * as yup from 'yup'

const schema = yup.object({
  name: yup.string().required('Name is required'),
  description: yup.string(),
})

export default function BasicForm() {
  const onSubmit = (params) => {
    console.log(params)
    return new Promise((resolve) => {
      setTimeout(resolve, 1000)
    })
  }

  return (
    <Form
      schema={schema}
      defaultValues={{
        name: 'Saas UI',
        description: '',
      }}
      onSubmit={onSubmit}
    >
      {({ Field }) => (
        <FormLayout>
          <Field
            name="name"
            label="Name"
            type="text"
            help="Choose a name for this project"
            rules={{ required: true }}
          />

          <Field
            name="description"
            type="textarea"
            label="Description"
            placeholder="Optional description"
          />

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

Schema resolvers#

Form supports all React Hook Form resolvers out of the box.

function CreateProject() {
  const schema = yup.object().shape({
    name: yup.string().required().label('Name'),
    description: yup.string().label('Description').min(50),
  })

  const onSubmit = (params) => {
    console.log(params)
    return new Promise((resolve) => {
      setTimeout(resolve, 1000)
    })
  }

  return (
    <Form
      defaultValues={{
        name: '',
        description: '',
      }}
      resolver={yupResolver(schema)}
      onSubmit={onSubmit}
    >
      <FormLayout>
        <Field
          name="name"
          label="Name"
          type="text"
          help="Choose a title for this project."
        />

        <Field
          name="description"
          type="textarea"
          label="Description"
          help="Minimum 50 characters."
        />

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

Disable the submit button when untouched#

You can disable the submit button when the form is untouched by passing the disableIfUntouched prop to the SubmitButton component. The SubmitButton will be disabled until the user interacts with any of the fields.

import { Form, FormLayout, SubmitButton } from '@saas-ui/react'

export default function DisableIfUntouched() {
  return (
    <Form onSubmit={saveHandler}>
      {({ Field }) => (
        <FormLayout>
          <Field
            name="title"
            label="Title"
            rules={{ required: 'Title is required' }}
          />
          <Field name="description" type="textarea" label="Description" />
          <SubmitButton disableIfUntouched />
        </FormLayout>
      )}
    </Form>
  )
}

Disable the submit button when invalid#

To disable the submit button when the form is invalid, pass the disableIfInvalid prop to the SubmitButton component. The SubmitButton will be disabled until the user fixes all the errors.

import { Form, FormLayout, SubmitButton } from '@saas-ui/react'

export default function DisableIfInvalid() {
  return (
    <Form onSubmit={saveHandler}>
      {({ Field }) => (
        <FormLayout>
          <Field
            name="email"
            label="Email"
            rules={{ required: true, type: 'email' }}
          />
          <Field
            name="terms"
            type="checkbox"
            label="I accept the terms & conditions."
            rules={{ required: true }}
          />
          <SubmitButton disableIfInvalid />
        </FormLayout>
      )}
    </Form>
  )
}

Use your own submit button#

Use any button with type="submit" to submit the form.

import { Form, FormLayout, SubmitButton } from '@saas-ui/react'

export default function CustomSubmit() {
  return (
    <Form onSubmit={saveHandler}>
      {({ Field, formState }) => (
        <FormLayout>
          <Field name="title" label="Title" />

          <Button
            type="submit"
            colorScheme="teal"
            isLoading={formState.isSubmitting}
          >
            Submit
          </Button>
        </FormLayout>
      )}
    </Form>
  )
}

import { Heading } from '@chakra-ui/react'
import { Form, FormLayout, SubmitButton } from '@saas-ui/react'

export default function GroupedFields() {
  return (
    <Form onSubmit={saveHandler}>
      {({ Field }) => (
        <FormLayout>
          <Heading size="md">Personal information</Heading>
          <FormLayout columns="2">
            <Field name="firstname" label="Name" />
            <Field name="lastname" label="Last name" />
          </FormLayout>

          <Field name="email" label="Email address" />

          <Heading size="md" mt="4">
            Address
          </Heading>
          <FormLayout>
            <Field name="address" label="Address" />
            <Field name="city" label="City" />
          </FormLayout>

          <Heading size="md" mt="4">
            Billing information
          </Heading>
          <FormLayout columns="2">
            <Field name="card" label="Card number" />
            <FormLayout columns="2">
              <Field name="exp" label="Expiration date" />
              <Field name="cvc" label="CVC" />
            </FormLayout>
          </FormLayout>

          <SubmitButton>Complete order</SubmitButton>
        </FormLayout>
      )}
    </Form>
  )
}

Conditionally show fields#

import { Heading } from '@chakra-ui/react'
import { Form, FormLayout, SubmitButton } from '@saas-ui/react'

export default function ConditionalFields() {
  return (
    <Form onSubmit={saveHandler}>
      {({ Field, DisplayIf }) => (
        <FormLayout>
          <Heading size="md">Personal information</Heading>
          <FormLayout columns="2">
            <Field name="firstname" label="Name" />
            <Field name="lastname" label="Last name" />
          </FormLayout>

          <Field name="email" label="Email address" />

          <Field
            name="ship"
            type="checkbox"
            value={true}
            label="Ship to my home address"
          />

          <DisplayIf
            name="ship"
            condition={(ship) => !!ship}
            onToggle={(matches) => console.log(matches)}
          >
            <FormLayout>
              <Heading size="md" mt="4">
                Address
              </Heading>
              <FormLayout>
                <Field name="address" label="Address" />
                <Field name="city" label="City" />
              </FormLayout>

              <Heading size="md" mt="4">
                Billing information
              </Heading>
              <FormLayout columns="2">
                <Field name="card" label="Card number" />
                <FormLayout columns="2">
                  <Field name="exp" label="Expiration date" />
                  <Field name="cvc" label="CVC" />
                </FormLayout>
              </FormLayout>
            </FormLayout>
          </DisplayIf>

          <SubmitButton>Complete order</SubmitButton>
        </FormLayout>
      )}
    </Form>
  )
}

Access the form context#

You can get access to the form context using a render prop, the useFormContext hook or the form ref.

Render prop#

import { Button } from '@chakra-ui/react'
import { Form, FormLayout, SubmitButton } from '@saas-ui/react'

export default function FormContext() {
  return (
    <Form onSubmit={saveHandler}>
      {({ formState, reset }) => (
        <FormLayout>
          <Field name="title" label="Title" />
          <Button onClick={() => reset()}>Reset</Button>
          <SubmitButton isLoading={formState.isSubmitting}>Submit</SubmitButton>
        </FormLayout>
      )}
    </Form>
  )
}

useFormContext#

import { Button } from '@chakra-ui/react'
import { Form, FormLayout, SubmitButton, useFormContext } from '@saas-ui/react'

function ResetButton() {
  const form = useFormContext()

  return <Button onClick={() => form.reset()}>Reset</Button>
}

export default function MyForm() {
  return (
    <Form onSubmit={saveHandler}>
      <FormLayout>
        <Field name="title" label="Title" />
        <ResetButton />
        <SubmitButton>Submit</SubmitButton>
      </FormLayout>
    </Form>
  )
}

Form ref#

function MyForm() {
  const formRef = useRef(null)

  return (
    <Form formRef={formRef} onSubmit={saveHandler}>
      <FormLayout>
        <Field name="title" label="Title" />
        <SubmitButton>Submit</SubmitButton>
        <Button onClick={() => formRef.current.reset()}>Reset</Button>
      </FormLayout>
    </Form>
  )
}

Defining custom form fields#

You can create custom form fields using the createField function. Once defined you can create a custom form using the createForm function.

In case you use Zod or Yup, you can use the createZodForm or createYupForm functions from @saas-ui/forms/zod or @saas-ui/forms/yup.

// form.tsx
import { createForm, createField } from '@saas-ui/react'

// zod
// import {createZodForm} from '@saas-ui/forms/zod'

// yup
// import {createYupForm} from '@saas-ui/forms/yup'

const MyCustomField = createField(
  React.forwardRef((props, ref) => {
    return <input ref={ref} {...props} />
  })
)

const MyCustomControlledField = createField(
  React.forwardRef((props, ref) => {
    return <ReactSelect ref={ref} {...props} />
  }),
  {
    isControlled: true,
  }
)

export const Form = createForm({
  fields: {
    custom: MyCustomField,
    'custom-controlled': MyCustomControlledField,
  },
})

Now you can use the custom field in your forms.

import { Form } from './form'

export default function MyForm = () => {
  return (
    <Form onSubmit={saveHandler}>
      {({Field}) => (
        <Field type="custom" name="custom" />
        <Field type="custom-controlled" name="customControlled" />
      )}
    </Form>
  )
}

Custom base field#

The base field is responsible for rendering the label, help text, error message and the input itself. You can configure a custom base field using the getBaseField prop of createForm.

You can configure extraProps that can be passed to the Field component and will be available in your custom BaseField component.

import {
  Box,
  FormControl,
  FormLabel,
  FormHelpText,
  FormErrorMessage,
  HStack,
  Tooltip,
} from '@chakra-ui/react'
import { createForm, useBaseField, splitProps } from '@saas-ui/react'
import { LuInfo } from 'react-icons/lu'

const getBaseField: GetBaseField<{ infoLabel?: string }> = () => {
  return {
    extraProps: ['infoLabel'],
    BaseField: (props) => {
      const [{ children, infoLabel }, fieldProps] = splitProps(props, [
        'children',
        'infoLabel',
      ])

      const { controlProps, label, help, hideLabel, error } =
        useBaseField(fieldProps)

      return (
        <FormControl {...controlProps} isInvalid={!!error}>
          {!hideLabel ? (
            <HStack alignItems="center" mb="2" spacing="0">
              <FormLabel mb="0">{label}</FormLabel>
              {infoLabel ? (
                <Tooltip label={infoLabel}>
                  <span>
                    <LuInfo />
                  </span>
                </Tooltip>
              ) : null}
            </HStack>
          ) : null}
          <Box>
            {children}
            {help && !error?.message ? (
              <FormHelperText>{help}</FormHelperText>
            ) : null}
            {error?.message && (
              <FormErrorMessage>{error?.message}</FormErrorMessage>
            )}
          </Box>
        </FormControl>
      )
    },
  }
}

export const Form = createForm({
  getBaseField,
})

Accessibility#

The Form component wraps the children in a HTML <form> element.

Keyboard Interaction#

Key	Action
`Enter`	Submit the form

Was this helpful?