Form

Usage

Form and its child components FormFields and FormActions are designed to make creating forms simple and consistent. Using the these components has a number of benefits:

• Ensure the HTML form component is used and has the novalidate prop set by default
• Standardise the spacing between form fields, notifications, and CTAs
• Ensure that error summaries and notifications are consistently and conveniently used
• Ensure error notifications receive keyboard focus when they appear

Edit live code
<Form>
  <FormFields>
    <TextField name="first-name" id="first-name" label="First name" />
    <TextField name="last-name" id="last-name" label="Last name" />
    <Checkbox name="terms" label="I agree to the terms & conditions" />
  </FormFields>
  <FormActions>
    <PrimaryCTAButton>Submit</PrimaryCTAButton>
    <SecondaryCTAButton>Clear</SecondaryCTAButton>
  </FormActions>
</Form>
<Form>
  <FormFields>
    <TextField name="first-name" id="first-name" label="First name" />
    <TextField name="last-name" id="last-name" label="Last name" />
    <Checkbox name="terms" label="I agree to the terms & conditions" />
  </FormFields>
  <FormActions>
    <PrimaryCTAButton>Submit</PrimaryCTAButton>
    <SecondaryCTAButton>Clear</SecondaryCTAButton>
  </FormActions>
</Form>

FormFields

The FormFields component manages the vertical spacing of their direct children using the Stack component.

Avoid placing anything other than fields and actions in this component. In cases where it is essential that other content is added it is recommend to ensure that it is wrapped in a <div>.

Do:

Edit live code
<FormFields>
  <TextField name="first-name" id="first-name" label="First name" />
  <TextField name="last-name" id="last-name" label="Last name" />
  <div>
    <P>Example showing that a paragraph within a div receives the correct spacing.</P>
  </div>
</FormFields>
<FormFields>
  <TextField name="first-name" id="first-name" label="First name" />
  <TextField name="last-name" id="last-name" label="Last name" />
  <div>
    <P>Example showing that a paragraph within a div receives the correct spacing.</P>
  </div>
</FormFields>

Don't:

Edit live code
<FormFields>
  <TextField name="first-name" id="first-name" label="First name" />
  <TextField name="last-name" id="last-name" label="Last name" />
  <P>Example showing that a paragraph placed directly conflicts with intended spacing.</P>
</FormFields>
<FormFields>
  <TextField name="first-name" id="first-name" label="First name" />
  <TextField name="last-name" id="last-name" label="Last name" />
  <P>Example showing that a paragraph placed directly conflicts with intended spacing.</P>
</FormFields>

FormActions

The FormActions component manages the horizontal spacing of their direct children using the Cluster component. It also manages the vertical spacing from the FormFields using the Margin component.

Edit live code
<FormActions>
  <PrimaryCTAButton>Submit</PrimaryCTAButton>
  <SecondaryCTAButton>Clear</SecondaryCTAButton>
</FormActions>
<FormActions>
  <PrimaryCTAButton>Submit</PrimaryCTAButton>
  <SecondaryCTAButton>Clear</SecondaryCTAButton>
</FormActions>

Errors

The form component makes it easy to consistently show errors related to forms, ensuring that they are located in the correct place at the top of the form and automatically receive keyboard focus when they appear.

Error summary

Error summary should be used when there are issues with the user input, related to specific fields. The summary will list all issues and link to the relevant field.

The error summary will automatically receive keyboard focus when it appears.

Edit live code
() => {
  const [errors] = useState([
    { id: 'first-name', message: 'Must enter a first name' },
    { id: 'last-name', message: 'Must enter a last name' }
  ]);

  return (
    <Inert /* Ignore - prevent auto-focus for this example. */>
      <Form errors={errors}>
        <FormFields>
          <TextField
            name="first-name"
            id="first-name"
            label="First name"
          />
          <TextField
            name="last-name"
            id="last-name"
            label="Last name"
          />
        </FormFields>
        <FormActions>
          <PrimaryCTAButton>Submit</PrimaryCTAButton>
          <SecondaryCTAButton>Clear</SecondaryCTAButton>
        </FormActions>
      </Form>
    </Inert>
  )
}
() => {
  const [errors] = useState([
    { id: 'first-name', message: 'Must enter a first name' },
    { id: 'last-name', message: 'Must enter a last name' }
  ]);

  return (
    <Inert /* Ignore - prevent auto-focus for this example. */>
      <Form errors={errors}>
        <FormFields>
          <TextField
            name="first-name"
            id="first-name"
            label="First name"
          />
          <TextField
            name="last-name"
            id="last-name"
            label="Last name"
          />
        </FormFields>
        <FormActions>
          <PrimaryCTAButton>Submit</PrimaryCTAButton>
          <SecondaryCTAButton>Clear</SecondaryCTAButton>
        </FormActions>
      </Form>
    </Inert>
  )
}

General Error

Sometimes things go wrong that aren't related to a specific field, for example and API timing out. These errors should not use the error summary but instead show a general error that explains what has happened and what the user should do.

Like error summaries, these notifications will automatically receive keyboard focus when they appear.

Edit live code
<Inert /* Ignore - prevent auto-focus for this example. */>
  <Form generalError={{
    title: 'Request time out',
    message: <P>Your form data was not submitted, please try again.</P>,
  }}>
    <FormFields>
      <TextField name="first-name" id="first-name" label="First name" />
      <TextField name="last-name" id="last-name" label="Last name" />
    </FormFields>
    <FormActions>
      <PrimaryCTAButton>Submit</PrimaryCTAButton>
      <SecondaryCTAButton>Clear</SecondaryCTAButton>
    </FormActions>
  </Form>
</Inert>
<Inert /* Ignore - prevent auto-focus for this example. */>
  <Form generalError={{
    title: 'Request time out',
    message: <P>Your form data was not submitted, please try again.</P>,
  }}>
    <FormFields>
      <TextField name="first-name" id="first-name" label="First name" />
      <TextField name="last-name" id="last-name" label="Last name" />
    </FormFields>
    <FormActions>
      <PrimaryCTAButton>Submit</PrimaryCTAButton>
      <SecondaryCTAButton>Clear</SecondaryCTAButton>
    </FormActions>
  </Form>
</Inert>

Using the form context

Nebula components will automatically check for the Form Context when used within the Form component to check for any errors, but if you want this automation for you own reusable components you will need to check this yourself.

If using Nebula's Field sub-component (see documentation) you may find this already works:

import { Field } from "@kaluza-platform/nebula";

export const MyField = (props, ref) =>  (
  <Field {...props}>
    <MyInput ref={ref} />
  </Field>
);
import { Field } from "@kaluza-platform/nebula";

export const MyField = (props, ref) =>  (
  <Field {...props}>
    <MyInput ref={ref} />
  </Field>
);

If you are not using the Field component you will need to add the check yourself. For example:

import { useFormFieldError } from "@kaluza-platform/nebula";

const MyCustomField = ({ name, error: errorFromProps }) => {
  const errorFromContext = useFormFieldError(name);
  const error = errorFromProps || errorFromContext;

  return <MyInput error={error}>
}
import { useFormFieldError } from "@kaluza-platform/nebula";

const MyCustomField = ({ name, error: errorFromProps }) => {
  const errorFromContext = useFormFieldError(name);
  const error = errorFromProps || errorFromContext;

  return <MyInput error={error}>
}

Properties

Form

FormFields

FormActions

Related

• Form Guidelines
• Notification