mirror of
https://github.com/supabase/supabase.git
synced 2026-10-15 14:19:11 +03:00
Danny White
b23c6a7fed
## What kind of change does this PR introduce? Chore that references DEPR-394. ## What is the current behavior? Key/value editors for headers are implemented separately in multiple places. ## What is the new behavior? DEPR-394 is consolidating repeated RHF field-array UIs across Studio and the design system. - adds a shared `KeyValueFieldArray` component in `ui-patterns` - adds a shared `httpHeaderAddActions` helper for preset header rows - migrates the key/value header editors in: - Platform Webhooks - Cron Jobs HTTP headers - Database Webhooks HTTP headers - documents the key/value pattern in the design system with: - a dedicated fragment page - updated forms guidance - updated form pattern demos | Preview | | --- | | <img width="1102" height="420" alt="CleanShot 2026-03-23 at 12 22 18@2x" src="https://github.com/user-attachments/assets/f8d23ff9-7063-462f-8074-b400561f77e9" /> | ## Additional context This is PR 1 of a 3-PR stack for DEPR-394.
59 lines
2.6 KiB
Plaintext
59 lines
2.6 KiB
Plaintext
---
|
|
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 [Key/Value Field Array](../fragments/key-value-field-array) fragment when each row is two text inputs managed by `react-hook-form`. Keep using a plain field array when each row is just one input, and build a custom row when the cells are mixed controls.
|
|
|
|
## 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_Shadcn_` 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`.
|
|
|
|
6. **Error handling**: Always use mutations with `onSuccess` and `onError` callbacks that show toast notifications.
|
|
|
|
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.
|