Anatomy
- Form: Wraps form controls, manages their disabled states, and handles form submission.
- Title: Describes the main purpose of the Form.
- Description: Supplements the title with more contextual information about the Form.
- Form controls: Accepts user's input required to complete and submit the form.
- Secondary action: Alternative action to submitting, such as canceling.
- Primary action: Submits the form.
Guidelines
When to use
The Form component serves as a fieldset container that wraps other Pluma form controls. It allows for easy handling of submission, automatic loading states, and controls the disabled state of all child form controls.
Forms are widespread and commonly seen in, but not limited to, the following scenarios and examples:
- Settings pages: Editing profile details, workspace configuration, or API key management.
- Modal forms: Creating or editing resources inside a Modal, where the submit button lives in the Modal footer outside the form body.
- Inline editors: Short forms embedded in drawers, popovers, or directly on the page.
Form length
When creating forms, add only the most necessary fields required for completion. Shorter forms result in a better user experience and lead to higher form completion rates.
Best practices
Pairing with FormLayout
Creating form layouts is made easy when the Form and FormLayout components are paired together. While the Form handles data submission and field state, the FormLayout handles field grouping and gap customization.
FormLayouts are not required, but in adherence to consistency across the design system, they are recommended.
Use the FormLayoutGroup subcomponent to place related short fields side by side, such as first and last name, or city and state. Each field in the group receives equal width. Unrelated fields should stack vertically.
Behaviors
Disabled
When disabled, all nested form controls become non-interactive and submission events are blocked. Disabling is best used for restricting access or edits to the form unless permission is granted or displaying read-only data.
All fields are interactive and the form accepts submissions.
Fields are disabled and submission is blocked, but existing input values are still displayed.
Content
Error handling
Validation errors are important for communicating that some part of the form must be addressed before submission. Display errors using the form control's built-in error message prop. Avoid creating errors as a separate summary at the top or bottom of the form. Be clear about what's missing or what action the user can take to address the error.