---
title: Forms
description: Common form patterns used in Studio settings pages and side panels.
---

Forms in Supabase Studio should follow consistent patterns to ensure a cohesive user experience across settings pages and side panels. This guide covers the most common form patterns and field types.

## Page Layout

Forms in page layouts typically use `PageSection` components with `Card` containers. Fields use `FormItemLayout` with `layout="flex-row-reverse"` for horizontal alignment.

<ComponentPreview
  name="form-patterns-pagelayout"
  description="Complete form example with all field types in a PageLayout pattern"
  peekCode
  wide
/>

## Side Panel

Forms in side panels (Sheets) use `FormItemLayout` with `layout="horizontal"` on wider panels and `layout="vertical"` on panels with a size of `sm` or below. The form is typically wrapped in a `Sheet` component.

<ComponentPreview
  name="form-patterns-sidepanel"
  description="Complete form example with all field types in a SidePanel/Sheet pattern"
  peekCode
  wide
/>

## Field Arrays

The form previews above include both repeated-field patterns used across Studio:

- **Field Array** for repeated single-value rows such as redirect URIs.
- **Key/Value Field Array** for repeated text pairs such as headers, parameters, and config entries.

Use the shared [Single Value Field Array](../fragments/single-value-field-array) fragment when each row is one text input managed by `react-hook-form`.

Use the shared [Key/Value Field Array](../fragments/key-value-field-array) fragment when each row is two text inputs managed by `react-hook-form`.

Keep repeated-row validation in the form schema or shared validation helper, not in the fragment component itself.

Build a custom row when the cells are mixed controls, such as an input paired with a `Select`.

## Best practices

1. **Always use FormItemLayout**: Use `FormItemLayout` instead of manually composing `FormItem`, `FormLabel`, `FormMessage`, and `FormDescription`.

2. **Layout selection**:
   - Use `layout="flex-row-reverse"` for page layouts (horizontal alignment)
   - Use `layout="horizontal"` for side panels with more width
   - Use `layout="vertical"` for side panels with limited width

3. **Wrap inputs in FormControl*Shadcn***: Always wrap form inputs with `FormControl` to ensure proper form integration.

4. **Use Cards for grouping**: Wrap form sections in `Card` components with `CardContent` and `CardFooter` for actions.

5. **Handle dirty state**: Show cancel buttons and disable save buttons based on `form.formState.isDirty`. Make sure you destructure `isDirty` from `form.formState` (see https://react-hook-form.com/docs/useform/formstate). When the form is in a dialog or sheet, also follow [Dirty form dismissal](./modality#dirty-form-dismissal) so Cancel, Escape, and backdrop ask before discarding unsaved changes.

6. **Error handling**: Match feedback to its scope. Use `FormMessage` or `FieldError` for field validation. Show submission failures inline near the form actions when the user needs to retry or change something. Reserve toasts for non-blocking feedback or completed operations whose originating surface is no longer visible.

7. **Loading states**: Show loading states on submit buttons using the `loading` prop.

8. **Form IDs**: When submit buttons are outside the form, use a form ID and reference it with the `form` prop on the button.