+
+
+
+ Total Requests
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
+
+
+
+ Standard Bar Chart
+
+
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
+
+
+
+
+
+
+
+ Standard Line Chart
+
+
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
+
+
+
+ Standard Bar Chart
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
)
diff --git a/apps/design-system/config/docs.ts b/apps/design-system/config/docs.ts
index 4c921fd1170..23d40fb6ff5 100644
--- a/apps/design-system/config/docs.ts
+++ b/apps/design-system/config/docs.ts
@@ -9,6 +9,7 @@ export const docsConfig: DocsConfig = {
sidebarNav: [
{
title: 'Getting Started',
+ sortOrder: 'manual',
items: [
{
title: 'Introduction',
@@ -49,15 +50,17 @@ export const docsConfig: DocsConfig = {
},
{
title: 'UI Patterns',
+ sortOrder: 'alphabetical',
items: [
{
- title: 'Navigation',
- href: '/docs/ui-patterns/navigation',
+ title: 'Introduction',
+ href: '/docs/ui-patterns/ui-patterns',
items: [],
+ priority: true,
},
{
- title: 'Layout',
- href: '/docs/ui-patterns/layout',
+ title: 'Charts',
+ href: '/docs/ui-patterns/charts',
items: [],
},
{
@@ -70,15 +73,32 @@ export const docsConfig: DocsConfig = {
href: '/docs/ui-patterns/forms',
items: [],
},
+ {
+ title: 'Layout',
+ href: '/docs/ui-patterns/layout',
+ items: [],
+ },
+ {
+ title: 'Navigation',
+ href: '/docs/ui-patterns/navigation',
+ items: [],
+ },
+ {
+ title: 'Tables',
+ href: '/docs/ui-patterns/tables',
+ items: [],
+ },
],
},
{
title: 'Fragment Components',
+ sortOrder: 'alphabetical',
items: [
{
title: 'Introduction',
- href: '/docs/components/fragment-components',
+ href: '/docs/fragments/fragment-components',
items: [],
+ priority: true,
},
{
title: 'Admonition',
@@ -169,11 +189,13 @@ export const docsConfig: DocsConfig = {
},
{
title: 'Atom Components',
+ sortOrder: 'alphabetical',
items: [
{
title: 'Introduction',
href: '/docs/components/atom-components',
items: [],
+ priority: true,
},
{
title: 'Accordion',
@@ -231,11 +253,6 @@ export const docsConfig: DocsConfig = {
href: '/docs/components/carousel',
items: [],
},
- {
- title: 'Chart',
- href: '/docs/components/chart',
- items: [],
- },
{
title: 'Checkbox',
href: '/docs/components/checkbox',
@@ -266,11 +283,6 @@ export const docsConfig: DocsConfig = {
href: '/docs/components/context-menu',
items: [],
},
- {
- title: 'Data Table',
- href: '/docs/components/data-table',
- items: [],
- },
{
title: 'Date Picker',
href: '/docs/components/date-picker',
@@ -291,6 +303,11 @@ export const docsConfig: DocsConfig = {
href: '/docs/components/dropdown-menu',
items: [],
},
+ {
+ title: 'Field',
+ href: '/docs/components/field',
+ items: [],
+ },
{
title: 'Form',
href: '/docs/components/form',
diff --git a/apps/design-system/content/docs/accessibility.mdx b/apps/design-system/content/docs/accessibility.mdx
index 8677b350c52..35bebb64804 100644
--- a/apps/design-system/content/docs/accessibility.mdx
+++ b/apps/design-system/content/docs/accessibility.mdx
@@ -27,29 +27,33 @@ Chromium-based browsers and Firefox handle this automatically via the Tab key. S
Interactive page elements should also provide visual feedback upon selection via a `focus-visible` state. We use consistent focus styles such as `inset-focus` so users recognize this state instantly.
-[Button](../components/button) has all of the above built-in. Bespoke interactive elements however, such as the below clickable [TableRow](../components/table), require these props to be added manually:
+[Button](components/button) has all of the above built-in. Bespoke interactive elements however, such as the below interactive [Table Row](components/table#examples), require these props to be added manually:
-```tsx showLineNumbers {3, 5-11}
+```tsx showLineNumbers {4-14}
handleBucketNavigation(name, event)}
+ onClick={(event) => {
+ if (event.currentTarget !== event.target) return
+ handleBucketNavigation(bucket.id, event)
+ }}
onKeyDown={(event) => {
+ if (event.currentTarget !== event.target) return
if (event.key === 'Enter' || event.key === ' ') {
event.preventDefault()
- handleBucketNavigation(name, event)
+ handleBucketNavigation(bucket.id, event)
}
}}
tabIndex={0}
>
-
-
{name}
-
+ {name}
```
Consider also affordances like `ctrl` and `meta` key support for opening in a new tab. Anything that you can do with a mouse input should be replicable by keyboard.
+See the examples within [Table](components/table#examples) for more.
+
### Radio groups
Single-select option groups such as `` should behave as a single control. Only the first item of radio groups should become focused with the Tab key. The next Tab should move focus from the group to the next focusable control.
diff --git a/apps/design-system/content/docs/components/alert.mdx b/apps/design-system/content/docs/components/alert.mdx
index 5923eaf90d9..3204cf452e8 100644
--- a/apps/design-system/content/docs/components/alert.mdx
+++ b/apps/design-system/content/docs/components/alert.mdx
@@ -7,47 +7,19 @@ source:
shadcn: true
---
-The primitive component that forms [Admonition](../fragments/admonition). Do not use this component unless you are intentionally deviating from our consistent callout pattern.
+Alert forms the core primitives for [Admonition](../fragments/admonition). Use the Admonition component unless you must deviate from our consistent patterns. Examples where Alert might make sense include:
-
+- Bespoke icon requirement
+- Highly custom internal contents
+
+
## Installation
-
-
-
- CLI
- Manual
-
-
-
```bash
npx shadcn-ui@latest add alert
```
-
-
-
-
-
-
-Copy and paste the following code into your project.
-
-
-
-Update the import paths to match your project setup.
-
-
-
-
-
-
-
## Usage
```tsx
@@ -63,19 +35,3 @@ import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'
```
-
-## Examples
-
-### Default
-
-
-
-### Destructive
-
-
diff --git a/apps/design-system/content/docs/components/atom-components.mdx b/apps/design-system/content/docs/components/atom-components.mdx
index 8952b428085..8022af4294d 100644
--- a/apps/design-system/content/docs/components/atom-components.mdx
+++ b/apps/design-system/content/docs/components/atom-components.mdx
@@ -1,4 +1,10 @@
---
title: Atom components
-description:
+description: Fundamental building blocks of user interfaces, based on shadcn/ui components.
---
+
+Atom components are the fundamental building blocks of our design system. These are primitive, single-purpose components that serve as the foundation for building more complex interfaces. Unlike fragment components (pre-built composite components) or UI patterns (guidelines for structuring sections), atom components are the smallest reusable units that can be composed together.
+
+These components are based on [shadcn/ui](https://ui.shadcn.com) and live in the `ui` package, making them shareable across all Supabase applications. They provide consistent styling, accessibility, and behavior for common interface elements like buttons, inputs, cards, dialogs, and form controls.
+
+Atom components are imported from the `ui` package and can be used directly or combined to create fragment components and implement UI patterns. They form the base layer of our component architecture, ensuring visual and functional consistency across the entire design system.
diff --git a/apps/design-system/content/docs/components/data-table.mdx b/apps/design-system/content/docs/components/data-table.mdx
deleted file mode 100644
index d2e6620145e..00000000000
--- a/apps/design-system/content/docs/components/data-table.mdx
+++ /dev/null
@@ -1,842 +0,0 @@
----
-title: Data Table
-description: Powerful table and datagrids built using TanStack Table.
-component: true
-links:
- doc: https://tanstack.com/table/v8/docs/guide/introduction
----
-
-
-
-## Introduction
-
-Every data table or datagrid I've created has been unique. They all behave differently, have specific sorting and filtering requirements, and work with different data sources.
-
-It doesn't make sense to combine all of these variations into a single component. If we do that, we'll lose the flexibility that [headless UI](https://tanstack.com/table/v8/docs/guide/introduction#what-is-headless-ui) provides.
-
-So instead of a data-table component, I thought it would be more helpful to provide a guide on how to build your own.
-
-We'll start with the basic `
` component and build a complex data table from scratch.
-
-
-
-**Tip:** If you find yourself using the same table in multiple places in your app, you can always extract it into a reusable component.
-
-
-
-## Table of Contents
-
-This guide will show you how to use [TanStack Table](https://tanstack.com/table) and the `
` component to build your own custom data table. We'll cover the following topics:
-
-- [Basic Table](#basic-table)
-- [Row Actions](#row-actions)
-- [Pagination](#pagination)
-- [Sorting](#sorting)
-- [Filtering](#filtering)
-- [Visibility](#visibility)
-- [Row Selection](#row-selection)
-- [Reusable Components](#reusable-components)
-
-## Installation
-
-1. Add the `
` component to your project:
-
-```bash
-npx shadcn-ui@latest add table
-```
-
-2. Add `tanstack/react-table` dependency:
-
-```bash
-npm install @tanstack/react-table
-```
-
-## Prerequisites
-
-We are going to build a table to show recent payments. Here's what our data looks like:
-
-```tsx showLineNumbers
-type Payment = {
- id: string
- amount: number
- status: 'pending' | 'processing' | 'success' | 'failed'
- email: string
-}
-
-export const payments: Payment[] = [
- {
- id: '728ed52f',
- amount: 100,
- status: 'pending',
- email: 'm@example.com',
- },
- {
- id: '489e1d42',
- amount: 125,
- status: 'processing',
- email: 'example@gmail.com',
- },
- // ...
-]
-```
-
-## Project Structure
-
-Start by creating the following file structure:
-
-```txt
-app
-└── payments
- ├── columns.tsx
- ├── data-table.tsx
- └── page.tsx
-```
-
-I'm using a Next.js example here but this works for any other React framework.
-
-- `columns.tsx` (client component) will contain our column definitions.
-- `data-table.tsx` (client component) will contain our `` component.
-- `page.tsx` (server component) is where we'll fetch data and render our table.
-
-## Basic Table
-
-Let's start by building a basic table.
-
-
-
-### Column Definitions
-
-First, we'll define our columns.
-
-```tsx showLineNumbers title="app/payments/columns.tsx" {3,14-27}
-'use client'
-
-import { ColumnDef } from '@tanstack/react-table'
-
-// This type is used to define the shape of our data.
-// You can use a Zod schema here if you want.
-export type Payment = {
- id: string
- amount: number
- status: 'pending' | 'processing' | 'success' | 'failed'
- email: string
-}
-
-export const columns: ColumnDef[] = [
- {
- accessorKey: 'status',
- header: 'Status',
- },
- {
- accessorKey: 'email',
- header: 'Email',
- },
- {
- accessorKey: 'amount',
- header: 'Amount',
- },
-]
-```
-
-
-
-**Note:** Columns are where you define the core of what your table
-will look like. They define the data that will be displayed, how it will be
-formatted, sorted and filtered.
-
-
-
-### `` component
-
-Next, we'll create a `` component to render our table.
-
-```tsx showLineNumbers title="app/payments/data-table.tsx"
-'use client'
-
-import { ColumnDef, flexRender, getCoreRowModel, useReactTable } from '@tanstack/react-table'
-
-import {
- Table,
- TableBody,
- TableCell,
- TableHead,
- TableHeader,
- TableRow,
-} from '@/components/ui/table'
-
-interface DataTableProps {
- columns: ColumnDef[]
- data: TData[]
-}
-
-export function DataTable({ columns, data }: DataTableProps) {
- const table = useReactTable({
- data,
- columns,
- getCoreRowModel: getCoreRowModel(),
- })
-
- return (
-
- )
-}
-```
-
-This adds a checkbox to each row and a checkbox in the header to select all rows.
-
-### Show selected rows
-
-You can show the number of selected rows using the `table.getFilteredSelectedRowModel()` API.
-
-```tsx
-
- {table.getFilteredSelectedRowModel().rows.length} of {table.getFilteredRowModel().rows.length}{' '}
- row(s) selected.
-
-```
-
-
-
-## Reusable Components
-
-Here are some components you can use to build your data tables. This is from the [Tasks](/examples/tasks) demo.
-
-### Column header
-
-Make any column header sortable and hideable.
-
-
-
-```tsx {5}
-export const columns = [
- {
- accessorKey: 'email',
- header: ({ column }) => ,
- },
-]
-```
-
-### Pagination
-
-Add pagination controls to your table including page size and selection count.
-
-
-
-```tsx
-
-```
-
-### Column toggle
-
-A component to toggle column visibility.
-
-
-
-```tsx
-
-```
diff --git a/apps/design-system/content/docs/components/dropdown-menu.mdx b/apps/design-system/content/docs/components/dropdown-menu.mdx
index daccc38aa88..e7fed432cd7 100644
--- a/apps/design-system/content/docs/components/dropdown-menu.mdx
+++ b/apps/design-system/content/docs/components/dropdown-menu.mdx
@@ -15,12 +15,6 @@ source:
## Installation
-So I guess I can write anything i want in here.
-
-## Props
-
-{/* */}
-
diff --git a/apps/design-system/content/docs/components/field.mdx b/apps/design-system/content/docs/components/field.mdx
new file mode 100644
index 00000000000..aa5e30a6542
--- /dev/null
+++ b/apps/design-system/content/docs/components/field.mdx
@@ -0,0 +1,333 @@
+---
+title: Field
+description: Combine labels, controls, and help text to compose accessible form fields and grouped inputs.
+component: true
+source:
+ shadcn: true
+---
+
+
+
+## Installation
+
+
+
+
+ CLI
+ Manual
+
+
+
+```bash
+npx shadcn@latest add field
+```
+
+
+
+
+
+
+
+Copy and paste the following code into your project.
+
+
+
+Update the import paths to match your project setup.
+
+
+
+
+
+
+
+## Usage
+
+```tsx showLineNumbers
+import {
+ Field,
+ FieldContent,
+ FieldDescription,
+ FieldError,
+ FieldGroup,
+ FieldLabel,
+ FieldLegend,
+ FieldSeparator,
+ FieldSet,
+ FieldTitle,
+} from '@/components/ui/field'
+```
+
+```tsx showLineNumbers
+
+```
+
+## Anatomy
+
+The `Field` family is designed for composing accessible forms. A typical field is structured as follows:
+
+```tsx showLineNumbers
+
+ Label
+ {/* Input, Select, Switch, etc. */}
+ Optional helper text.
+ Validation message.
+
+```
+
+- `Field` is the core wrapper for a single field.
+- `FieldContent` is a flex column that groups label and description. Not required if you have no description.
+- Wrap related fields with `FieldGroup`, and use `FieldSet` with `FieldLegend` for semantic grouping.
+
+## Form
+
+See the [Form](/docs/forms) documentation for building forms with the `Field` component and [React Hook Form](/docs/forms/react-hook-form) or [Tanstack Form](/docs/forms/tanstack-form).
+
+## Examples
+
+### Input
+
+
+
+### Textarea
+
+
+
+### Select
+
+
+
+### Slider
+
+
+
+### Fieldset
+
+
+
+### Checkbox
+
+
+
+### Radio
+
+
+
+### Switch
+
+
+
+### Choice Card
+
+Wrap `Field` components inside `FieldLabel` to create selectable field groups. This works with `RadioItem`, `Checkbox` and `Switch` components.
+
+
+
+### Field Group
+
+Stack `Field` components with `FieldGroup`. Add `FieldSeparator` to divide them.
+
+
+
+## Responsive Layout
+
+- **Vertical fields:** Default orientation stacks label, control, and helper text—ideal for mobile-first layouts.
+- **Horizontal fields:** Set `orientation="horizontal"` on `Field` to align the label and control side-by-side. Pair with `FieldContent` to keep descriptions aligned.
+- **Responsive fields:** Set `orientation="responsive"` for automatic column layouts inside container-aware parents. Apply `@container/field-group` classes on `FieldGroup` to switch orientations at specific breakpoints.
+
+
+
+## Validation and Errors
+
+- Add `data-invalid` to `Field` to switch the entire block into an error state.
+- Add `aria-invalid` on the input itself for assistive technologies.
+- Render `FieldError` immediately after the control or inside `FieldContent` to keep error messages aligned with the field.
+
+```tsx showLineNumbers /data-invalid/ /aria-invalid/
+
+ Email
+
+ Enter a valid email address.
+
+```
+
+## Accessibility
+
+- `FieldSet` and `FieldLegend` keep related controls grouped for keyboard and assistive tech users.
+- `Field` outputs `role="group"` so nested controls inherit labeling from `FieldLabel` and `FieldLegend` when combined.
+- Apply `FieldSeparator` sparingly to ensure screen readers encounter clear section boundaries.
+
+## API Reference
+
+### FieldSet
+
+Container that renders a semantic `fieldset` with spacing presets.
+
+| Prop | Type | Default |
+| ----------- | -------- | ------- |
+| `className` | `string` | |
+
+```tsx
+
+```
+
+### FieldLegend
+
+Legend element for a `FieldSet`. Switch to the `label` variant to align with label sizing.
+
+| Prop | Type | Default |
+| ----------- | --------------------- | ---------- |
+| `variant` | `"legend" \| "label"` | `"legend"` |
+| `className` | `string` | |
+
+```tsx
+Notification Preferences
+```
+
+The `FieldLegend` has two variants: `legend` and `label`. The `label` variant applies label sizing and alignment. Handy if you have nested `FieldSet`.
+
+### FieldGroup
+
+Layout wrapper that stacks `Field` components and enables container queries for responsive orientations.
+
+| Prop | Type | Default |
+| ----------- | -------- | ------- |
+| `className` | `string` | |
+
+```tsx
+
+ {/* ... */}
+ {/* ... */}
+
+```
+
+### Field
+
+The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing.
+
+| Prop | Type | Default |
+| -------------- | -------------------------------------------- | ------------ |
+| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` |
+| `className` | `string` | |
+| `data-invalid` | `boolean` | |
+
+```tsx
+
+ Remember me
+
+
+```
+
+### FieldContent
+
+Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no description.
+
+| Prop | Type | Default |
+| ----------- | -------- | ------- |
+| `className` | `string` | |
+
+```tsx
+
+
+
+ Notifications
+ Email, SMS, and push options.
+
+
+```
+
+### FieldLabel
+
+Label styled for both direct inputs and nested `Field` children.
+
+| Prop | Type | Default |
+| ----------- | --------- | ------- |
+| `className` | `string` | |
+| `asChild` | `boolean` | `false` |
+
+```tsx
+Email
+```
+
+### FieldTitle
+
+Renders a title with label styling inside `FieldContent`.
+
+| Prop | Type | Default |
+| ----------- | -------- | ------- |
+| `className` | `string` | |
+
+```tsx
+
+ Enable Touch ID
+ Unlock your device faster.
+
+```
+
+### FieldDescription
+
+Helper text slot that automatically balances long lines in horizontal layouts.
+
+| Prop | Type | Default |
+| ----------- | -------- | ------- |
+| `className` | `string` | |
+
+```tsx
+We never share your email with anyone.
+```
+
+### FieldSeparator
+
+Visual divider to separate sections inside a `FieldGroup`. Accepts optional inline content.
+
+| Prop | Type | Default |
+| ----------- | -------- | ------- |
+| `className` | `string` | |
+
+```tsx
+Or continue with
+```
+
+### FieldError
+
+Accessible error container that accepts children or an `errors` array (e.g., from `react-hook-form`).
+
+| Prop | Type | Default |
+| ----------- | ------------------------------------------ | ------- |
+| `errors` | `Array<{ message?: string } \| undefined>` | |
+| `className` | `string` | |
+
+```tsx
+
+```
+
+When the `errors` array contains multiple messages, the component renders a list automatically.
+
+`FieldError` also accepts issues produced by any validator that implements [Standard Schema](https://standardschema.dev/), including Zod, Valibot, and ArkType. Pass the `issues` array from the schema result directly to render a unified error list across libraries.
diff --git a/apps/design-system/content/docs/components/fragment-components.mdx b/apps/design-system/content/docs/components/fragment-components.mdx
deleted file mode 100644
index 1a924430a1f..00000000000
--- a/apps/design-system/content/docs/components/fragment-components.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: Fragment components
-description: ''
----
diff --git a/apps/design-system/content/docs/components/slider.mdx b/apps/design-system/content/docs/components/slider.mdx
index e2f1120559c..6f22de237df 100644
--- a/apps/design-system/content/docs/components/slider.mdx
+++ b/apps/design-system/content/docs/components/slider.mdx
@@ -59,3 +59,9 @@ import { Slider } from '@/components/ui/slider'
```tsx
```
+
+## Examples
+
+### Min and Max Range
+
+
diff --git a/apps/design-system/content/docs/components/table.mdx b/apps/design-system/content/docs/components/table.mdx
index 6dcafe2b601..c57ad66170c 100644
--- a/apps/design-system/content/docs/components/table.mdx
+++ b/apps/design-system/content/docs/components/table.mdx
@@ -1,64 +1,134 @@
---
title: Table
-description: A responsive table component for basic data.
+description: A responsive table component for presenting data inline.
component: true
+source:
+ shadcn: true
---
-Table presents basic tabular data presentation within a [Card](/docs/components/card).
+Table is an opinionated `
` element for basic tabular data presentation. It is usually presented within a [Card](../components/card).
-Columns will naturally take the width of their content. Width specification is therefore not required unless you require columns to span a specific width. An example use-case may be when placing multiple Table instances on the one page, where columns on each table should optically align.
-
-`TableHead` includes a `whitespace-nowrap` utility class to prevent its text from wrapping. `TableCell` must have any custom width specified, as there are legitimate use cases for both wrapping (or truncated) text.
-
## Usage
```tsx
import {
+ Card,
Table,
TableBody,
- TableCaption,
TableCell,
+ TableFooter,
TableHead,
TableHeader,
TableRow,
-} from '@/components/ui/table'
+} from 'ui'
```
```tsx
-
- A list of your recent invoices.
-
-
- Invoice
- Status
- Method
- Amount
-
-
-
-
- INV001
- Paid
- Credit Card
- $250.00
-
-
-
+
+
+
+
+ Column 1
+ Column 2
+ Column 3
+
+
+
+
+ Value 1
+ Value 2
+ Value 3
+
+
+
+
+ Total
+ Value
+
+
+
+
```
-## Sortable Columns
+## Layout
-Use `TableHeadSort` inside `TableHead` to enable column sorting.
+Columns will naturally take the width of their content unless otherwise specified. Specific column widths may be useful for controlling layout shift or for aligning multiple Table instances vertically.
+
+Table Head includes a `whitespace-nowrap` utility class to prevent its text from wrapping. Table Cell must have any custom width specified, as there are legitimate use cases for both wrapping (or truncated) text.
+
+The Table component is wrapped in a `ShadowScrollArea` by default, which provides horizontal scrolling on smaller screens when the table content exceeds the viewport width.
+
+## Structure
+
+Table is comprised of the following [Shadcn primitives](https://ui.shadcn.com/docs/components/table) which map directly to their HTML counterparts:
+
+| Component | HTML element |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| Table | [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tr) |
+
+Table and its child components follow their HTML element counterparts for semantics, accessibility, and best practices.
+
+### Table Caption
+
+Table Caption describes a table’s purpose or content. Think of it like the label of a diagram. It should only contain a single text node.
+
+Just like its `
` counterpart, Table Caption should be the first child of a Table element (before a Table Body) irrespective of its final visual positioning.
+
+### Table Footer
+
+Table Footer is a semantic grouping for the final rows of a table, typically used for column summaries, totals, or footnotes that relate to the data in the body of the table.
+
+Table Footer typically contains the same child elements as a Table Body, such as Table Row and Table Cell, and is a sibling of Table Body.
+
+## Examples
+
+### Empty state
+
+When displaying an empty state within a table, dim the Table Head text to indicate that no data is present. Use consistent zero results presentation across your application to maintain a cohesive user experience.
+
+
+
+To prevent the empty state row from being highlighted on hover, apply the `[&>td]:hover:bg-inherit` class to the Table Row containing the empty state message.
+
+```tsx showLineNumbers {1}
+
+
+
No results found
+
+ Your search for “test” did not return any results
+
+
+
+```
+
+See [Empty States](../ui-patterns/empty-states) for more information.
+
+### Sortable columns
+
+Use `TableHeadSort` inside Table Head to enable column sorting. This component provides visual indicators for sort state (ascending, descending, or unsorted) and handles click interactions.
+
+```tsx
+import { TableHeadSort } from 'ui'
+```
| Prop | Type | Description |
| -------------- | -------------------------- | ------------------------------------------------------------------ |
| `column` | `string` | Unique identifier for the column |
| `currentSort` | `string` | Current sort state in format `"column:order"` (e.g., `"name:asc"`) |
| `onSortChange` | `(column: string) => void` | Callback fired when column header is clicked |
+| `children` | `ReactNode` | The label text for the column header |
+| `className` | `string` | Optional additional CSS classes |
-```tsx
+```tsx showLineNumbers {2}
Name
@@ -66,10 +136,85 @@ Use `TableHeadSort` inside `TableHead` to enable column sorting.
```
-## Data Table
+The component displays:
-You can use the `
` component to build more complex data tables. Combine it with [@tanstack/react-table](https://tanstack.com/table/v8) to create tables with sorting, filtering and pagination.
+- An up arrow when the column is sorted ascending
+- A down arrow when the column is sorted descending
+- A chevrons icon when the column is not currently sorted (visible on hover)
-See the [Data Table](/docs/components/data-table) documentation for more information.
+
-You can also see an example of a data table in the [Tasks](/examples/tasks) demo.
+### Row icons
+
+When adding icon columns to your table, use [Accessibility](../accessibility) markup by including a screen reader-only label in the corresponding Table Head using the `sr-only` class. This ensures that assistive technologies can properly identify the column's purpose. Remove these icon cells when loading or displaying zero results to maintain a clean and consistent table structure.
+
+
+
+```tsx showLineNumbers {4, 5, 13, 14}
+
+
+
+
+ Icon
+
+ Name
+ Email
+
+
+
+
+
+
+
+ Value
+ Value
+
+
+
+```
+
+### Actions
+
+Action should be placed in the last column of each Table Row to maintain a logical reading flow. Users scan table data from left to right, so positioning actions on the right ensures they encounter the primary information first before reaching interactive controls.
+
+#### Multiple actions
+
+When multiple actions are available for a row, display one primary action as a button and place additional options in an overflow menu. This keeps the table clean and scannable while providing access to all necessary actions without overwhelming the user.
+
+
+
+#### Cross-links
+
+You may need to link to related resources from within table cells. In these cases, use the `text-link-table-cell` CSS class to provide a visual hint that the text is interactive while maintaining its appearance as tertiary content.
+
+
+
+Avoid making the entire row interactive when using cross-links. Multiple interactive areas within a single row increases the chance of mis-taps and creates ambiguity about which action will be triggered. Keep cross-links as discrete, scannable elements within their respective cells, and maintain a dedicated action column for primary row-level actions.
+
+#### Row-level navigation
+
+The entire Table Row may be tappable. This pattern is most effective when navigation is the sole or primary action for each row, as it provides a large, easy-to-target interaction area.
+
+Avoid adding other actions when using row-level navigation, as multiple interactive areas within a single row create competing affordances and increase interaction complexity.
+
+
+
+When implementing row-level navigation, pay close attention to [Accessibility](/accessibility#focus-management) requirements. The row must be keyboard accessible with proper focus management, including:
+
+- Handling `Enter` and `Space` key presses for activation
+- Providing visual focus indicators using classes like `inset-focus`
+- Supporting modifier keys (`Ctrl`/`Cmd`) for opening links in new tabs
+
+#### Row navigation with actions
+
+If you must combine row-level navigation with additional actions, nest all secondary actions in an overflow menu and maintain a [ChevronRight](https://lucide.dev/icons/chevron-right) visual indicator to signal that the row is navigable. This pattern preserves the primary navigation affordance while keeping secondary actions accessible but unobtrusive.
+
+
+
+This hybrid approach requires careful attention to event handling. Ensure that taps on action buttons stop event propagation to prevent triggering row navigation, and maintain clear visual separation between the navigable row area and the action controls.
+
+## Related
+
+Use the Table component for simple, static tabular data presentation with a fixed number of rows. Consider using [Data Table](../ui-patterns/tables#data-table) for more complex cases as it provides built-in sorting, filtering, and pagination capabilities.
+
+Refer to [Tables](../ui-patterns/tables) for broader guidance and best practices on presenting tabular data.
diff --git a/apps/design-system/content/docs/fragments/admonition.mdx b/apps/design-system/content/docs/fragments/admonition.mdx
index 5913866d970..0143008fcd9 100644
--- a/apps/design-system/content/docs/fragments/admonition.mdx
+++ b/apps/design-system/content/docs/fragments/admonition.mdx
@@ -4,7 +4,7 @@ description: Displays a callout for user attention.
fragment: true
---
-Admonition provides focus for situations that require a callout. Use this instead of [Alert](../components/alert) unless you specifically need the primitives.
+Admonition provides focus for situations that require a callout.
+Use Admonition instead of [Alert](../components/alert) unless you specifically need the primitives. If in doubt, stick with Admonition.
+
## Usage
```tsx
@@ -54,6 +56,13 @@ Only ever use the `primary` (green) button `type` on a `default` Admonition. Eve
className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]"
/>
+There are several components that wrap the `warning` Admonition type with reusable text or functionality. These include:
+
+- AlertError
+- NoPermission
+
+AlertError for example rolls up consistent error handling and support contact methods.
+
### Destructive
-
Why copy/paste and not packaged as a dependency?
@@ -20,5 +21,28 @@ One of the drawback of packaging the components in an npm package is that the st
+
+
+ Which libraries do you use?
+
+
+ We use the following libraries as a basis. Anywhere we use additional libraries, we document them in the individual component pages.
+
+ - [tailwindcss](https://tailwindcss.com)
+ - [shadcn/ui](https://ui.shadcn.com)
+ - [lucide-react](https://lucide.dev)
+ - [react-hook-form](https://react-hook-form.com)
+ You can find the full list of dependencies in the [package.json](https://github.com/supabase/design-system/blob/main/package.json) file.
+
+
+
+
+
+ I was looking for Supabase UI Library
+
+
+ If you are looking for the Supabase UI, you can find it [here](https://supabase.com/ui).
+
+
diff --git a/apps/design-system/content/docs/ui-patterns/charts.mdx b/apps/design-system/content/docs/ui-patterns/charts.mdx
new file mode 100644
index 00000000000..ef2b6cf8ad9
--- /dev/null
+++ b/apps/design-system/content/docs/ui-patterns/charts.mdx
@@ -0,0 +1,281 @@
+---
+title: Charts
+description: Composable charts for Reports, Dashboards and other visualizations.
+links:
+ doc: https://recharts.github.io/en-US/
+source:
+ recharts: true
+---
+
+
+
+## About
+
+Charts are an integral part of Observability at Supabase. Charts aim to be composable and reusable for frictionless setup.
+
+Our charts use a combination of our own presentational components and [Recharts](https://recharts.github.io/en-US/) for extensibility.
+
+## Best Practices
+
+1. **Use provided chart types first**: Always try to use the default provided charts first, otherwise passing Recharts compoennts to `` is possible but not recommended to avoid complexity.
+
+2. **Use the `useChart` context to show loading and disabled states**: The `useChart` context provides boolean flags for child components to show `isLoading` and `isDisabled` states.
+
+3. **Keep it simple**: Try to avoid abstracting the chart content too much. These components should cover most of your presentational needs.
+
+## Examples
+
+### Basic Chart Types
+
+
+
+### Chart States
+
+
+
+### Charts as Standalone Metrics
+
+
+
+### Charts with Actions
+
+
+
+### Chart with Table
+
+
+
+You can pass through our [Table](/docs/components/table) component to the `ChartFooter` and expect it to be styled correctly. There is no additional need to style the table, `ChartFooter` will handle the styling for you.
+
+## API
+
+### Chart
+
+The root container component that provides chart context to all child components.
+
+| Prop | Type | Default | Description |
+| ------------ | -------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `children` | `React.ReactNode` | - | Chart child components |
+| `isLoading` | `boolean` | `false` | Shows loading state in child components via the `useChart` context |
+| `isDisabled` | `boolean` | `false` | Disables chart interactions via the `useChart` context |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartCard
+
+A card wrapper for the chart. Can be used as a Card component or as a slot.
+
+| Prop | Type | Default | Description |
+| ----------- | -------------------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `children` | `React.ReactNode` | - | Chart content |
+| `asChild` | `boolean` | - | Render as child component (uses Slot) - ideal for removing the `Card` wrapper |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartHeader
+
+Container for chart header content like title and actions.
+
+| Prop | Type | Default | Description |
+| ----------- | -------------------------------------- | ---------- | ------------------------------------------------------------------- |
+| `children` | `React.ReactNode` | - | Header content (typically ChartTitle, ChartActions, or ChartMetric) |
+| `align` | `'start' \| 'center'` | `'center'` | Alignment of header content |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartTitle
+
+Displays the chart title with optional tooltip.
+
+| Prop | Type | Default | Description |
+| ----------- | -------------------------------------- | ------- | ------------------------------------- |
+| `children` | `React.ReactNode` | - | Title text |
+| `tooltip` | `string` | - | Tooltip text shown on help icon hover |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartActions
+
+Renders action buttons or links in the chart header.
+
+| Prop | Type | Default | Description |
+| ----------- | -------------------------------------- | ------- | ---------------------------------------------------------- |
+| `actions` | `ChartAction[]` | - | Array of action objects (see ChartAction type below) |
+| `children` | `React.ReactNode` | - | Custom action content (takes precedence over actions prop) |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+#### ChartAction Type
+
+| Property | Type | Description |
+| ----------- | -------------------- | ----------------------------------------------- |
+| `label` | `string` | Accessible label for the action |
+| `icon` | `React.ReactNode` | Icon component to display |
+| `onClick` | `() => void` | Click handler for button actions |
+| `href` | `string` | URL for link actions |
+| `type` | `'button' \| 'link'` | Action type (auto-detected if href is provided) |
+| `className` | `string` | Additional CSS classes |
+
+### ChartMetric
+
+Displays a metric value with optional status indicator.
+
+| Prop | Type | Default | Description |
+| ----------- | ---------------------------------------------------- | --------- | --------------------------------------------------- |
+| `label` | `string` | - | Metric label text |
+| `value` | `string \| number \| null \| undefined` | - | Metric value to display |
+| `diffValue` | `string \| number \| null \| undefined` | - | Differential value to display (shown as +/- change) |
+| `status` | `'positive' \| 'negative' \| 'warning' \| 'default'` | - | Status indicator color |
+| `align` | `'start' \| 'end'` | `'start'` | Alignment of the metric |
+| `tooltip` | `string` | - | Tooltip text shown on help icon hover |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartContent
+
+Container for the main chart visualization. Handles loading and empty states.
+
+| Prop | Type | Default | Description |
+| ----------------- | -------------------------------------- | ------- | -------------------------------------- |
+| `children` | `React.ReactNode` | - | Chart visualization content |
+| `isEmpty` | `boolean` | `false` | Whether to show empty state |
+| `emptyState` | `React.ReactNode` | - | Custom empty state component |
+| `loadingState` | `React.ReactNode` | - | Custom loading state component |
+| `disabledState` | `React.ReactNode` | - | Custom disabled state component |
+| `disabledActions` | `ChartAction[]` | - | Actions to show when chart is disabled |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartEmptyState
+
+Pre-built empty state component for charts.
+
+| Prop | Type | Default | Description |
+| ------------- | -------------------------------------- | ------- | ------------------------ |
+| `title` | `string` | - | Empty state title |
+| `description` | `string` | - | Empty state description |
+| `icon` | `React.ReactNode` | - | Optional icon to display |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartLoadingState
+
+Pre-built loading state component. Takes no props.
+
+### ChartFooter
+
+Container for footer content below the chart.
+
+| Prop | Type | Default | Description |
+| ----------- | -------------------------------------- | ------- | ---------------------- |
+| `children` | `React.ReactNode` | - | Footer content |
+| `className` | `string` | - | Additional CSS classes |
+| `...props` | `React.HTMLAttributes` | - | All standard div props |
+
+### ChartConfig
+
+Type definition for chart configuration used with Recharts components.
+
+```tsx
+type ChartConfig = {
+ [key: string]: {
+ label?: React.ReactNode
+ icon?: React.ComponentType
+ } & (
+ | { color?: string; theme?: never }
+ | { color?: never; theme: Record<'light' | 'dark', string> }
+ )
+}
+```
+
+| Property | Type | Description |
+| -------- | ----------------------------------- | -------------------------------------------------------- |
+| `label` | `React.ReactNode` | Label for the data series |
+| `icon` | `React.ComponentType` | Icon component for the data series |
+| `color` | `string` | Single color value (mutually exclusive with theme) |
+| `theme` | `Record<'light' \| 'dark', string>` | Theme-aware color values (mutually exclusive with color) |
+
+### ChartLine
+
+Line chart component for displaying time-series data.
+
+| Prop | Type | Default | Description |
+| ------------------- | --------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------- |
+| `data` | `ChartLineTick[]` | - | Array of data points with timestamp |
+| `dataKey` | `string` | - | Key in data object to plot |
+| `config` | `ChartConfig?` | - | Chart configuration for styling |
+| `onLineClick` | `(datum: ChartLineTick, tooltipData?: CategoricalChartState) => void` | - | Click handler for line points |
+| `DateTimeFormat` | `string` | `'MMM D, YYYY, hh:mma'` | Date format for tooltips and labels |
+| `isFullHeight` | `boolean` | `false` | Whether chart should take full height |
+| `className` | `string` | - | Additional CSS classes |
+| `color` | `string` | `'hsl(var(--brand-default))'` | Line color |
+| `hoverColor` | `string` | `'hsl(var(--brand-500))'` | Line color on hover |
+| `chartHighlight` | `ChartHighlight` | - | Highlight selection configuration |
+| `updateDateRange` | `(from: string, to: string) => void` | - | Callback when date range is updated via highlight |
+| `highlightActions` | `ChartHighlightAction[]` | - | Actions to show when area is highlighted |
+| `syncId` | `string` | - | ID to sync multiple charts |
+| `showHighlightArea` | `boolean` | `true` | Whether to show highlight area |
+| `cursor` | `string` | - | Cursor style (defaults to 'crosshair' if chartHighlight provided) |
+| `showGrid` | `boolean` | `false` | Whether to show grid lines |
+| `showYAxis` | `boolean` | `false` | Whether to show Y-axis |
+| `YAxisProps` | `object` | - | Additional Y-axis props (tick, tickFormatter, width, etc.) |
+| `strokeWidth` | `number` | `1.5` | Line stroke width |
+
+#### ChartLineTick Type
+
+| Property | Type | Description |
+| --------------- | ------------------ | ---------------------------- |
+| `timestamp` | `string` | Timestamp for the data point |
+| `[key: string]` | `string \| number` | Additional data fields |
+
+#### ChartHighlight Type
+
+| Property | Type | Description |
+| ----------------- | ------------------------------------------------------------- | ------------------------------------ |
+| `handleMouseDown` | `(e: { activeLabel?: string; coordinates?: string }) => void` | Mouse down handler |
+| `handleMouseMove` | `(e: { activeLabel?: string; coordinates?: string }) => void` | Mouse move handler |
+| `handleMouseUp` | `(e: { chartX?: number; chartY?: number }) => void` | Mouse up handler |
+| `coordinates` | `{ left?: string; right?: string }` | Highlight area coordinates |
+| `clearHighlight` | `() => void?` | Optional function to clear highlight |
+
+#### ChartHighlightAction Type
+
+| Property | Type | Description |
+| ------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `id` | `string` | Unique identifier for the action |
+| `label` | `string \| ((ctx: { start: string; end: string; clear: () => void }) => string)` | Action label or function that returns label |
+| `icon` | `ReactNode?` | Optional icon component |
+| `isDisabled` | `(ctx: { start: string; end: string; clear: () => void }) => boolean?` | Optional function to determine if action is disabled |
+| `onSelect` | `(ctx: { start: string; end: string; clear: () => void }) => void` | Action selection handler |
+
+### ChartBar
+
+Bar chart component for displaying time-series data.
+
+| Prop | Type | Default | Description |
+| ------------------- | -------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------- |
+| `data` | `ChartBarTick[]` | - | Array of data points with timestamp |
+| `dataKey` | `string` | - | Key in data object to plot |
+| `config` | `ChartConfig?` | - | Chart configuration for styling |
+| `onBarClick` | `(datum: ChartBarTick, tooltipData?: CategoricalChartState) => void` | - | Click handler for bars |
+| `DateTimeFormat` | `string` | `'MMM D, YYYY, hh:mma'` | Date format for tooltips and labels |
+| `isFullHeight` | `boolean` | `false` | Whether chart should take full height |
+| `className` | `string` | - | Additional CSS classes |
+| `color` | `string` | `'hsl(var(--brand-default))'` | Bar color |
+| `hoverColor` | `string` | `'hsl(var(--brand-500))'` | Bar color on hover |
+| `chartHighlight` | `ChartHighlight` | - | Highlight selection configuration |
+| `updateDateRange` | `(from: string, to: string) => void` | - | Callback when date range is updated via highlight |
+| `highlightActions` | `ChartHighlightAction[]` | - | Actions to show when area is highlighted |
+| `syncId` | `string` | - | ID to sync multiple charts |
+| `showHighlightArea` | `boolean` | `true` | Whether to show highlight area |
+| `cursor` | `string` | - | Cursor style (defaults to 'crosshair' if chartHighlight provided) |
+| `showGrid` | `boolean` | `false` | Whether to show grid lines |
+| `showYAxis` | `boolean` | `false` | Whether to show Y-axis |
+| `YAxisProps` | `object` | - | Additional Y-axis props (tick, tickFormatter, width, etc.) |
+
+#### ChartBarTick Type
+
+| Property | Type | Description |
+| --------------- | ------------------ | ---------------------------- |
+| `timestamp` | `string` | Timestamp for the data point |
+| `[key: string]` | `string \| number` | Additional data fields |
diff --git a/apps/design-system/content/docs/ui-patterns/empty-states.mdx b/apps/design-system/content/docs/ui-patterns/empty-states.mdx
index 709a72fba93..9199c4e37c8 100644
--- a/apps/design-system/content/docs/ui-patterns/empty-states.mdx
+++ b/apps/design-system/content/docs/ui-patterns/empty-states.mdx
@@ -14,7 +14,7 @@ There are two ways an empty state may be displayed in cases where there is no da
### Initial state
-Perhaps the user has not yet created any data. The presentation of this empty state depends on the context of the list and the type of data it contains.
+Perhaps the user has not yet created any data. The presentation of this empty state depends on the context of the list and the type of data it contains. Be mindful of the journey to rendering an empty state and any possible layout shift along the way.
#### Presentational
@@ -22,7 +22,7 @@ The user may be learning about a feature for the first time, and could benefit f
-Remember to use active language in these cases. For example: “Create a vector bucket” instead of “No vector buckets found”. The latter is more appropriate in table-based presentations, as described below.
+Remember to use active language in presentational empty states. For example: “Create a vector bucket” instead of “No vector buckets found”. The latter is more appropriate in table-based presentations, as described below.
#### Informational
@@ -42,13 +42,13 @@ A [Table](../components/table) instance with zero results should display a singl
-#### DataGrid
+#### Data Grid
-[DataGrid](../components/data-table) typically spans the full height and width of a container. A classic example is [Users](https://supabase.com/dashboard/project/_/auth/users), which (as it sounds) displays a list of the project’s registered users. Any instance with zero results should display a more prominent empty with a clear title, description, and supporting illustration.
+[Data Grid](../ui-patterns/tables#data-grid) and [Data Table](../ui-patterns/tables#data-table) component patterns typically span the full height and width of a container. A classic example is [Users](https://supabase.com/dashboard/project/_/auth/users), which (as it sounds) displays a list of the project’s registered users. Any instance with zero results should display a more prominent empty with a clear title, description, and supporting illustration.
-
+
-Other DataGrid instances include [Cron Jobs](https://supabase.com/dashboard/project/_/integrations/cron/jobs) and [Queues](https://supabase.com/dashboard/project/_/integrations/queues).
+Other Data Grid instances include [Cron Jobs](https://supabase.com/dashboard/project/_/integrations/cron/jobs) and [Queues](https://supabase.com/dashboard/project/_/integrations/queues).
## Missing route
@@ -61,7 +61,3 @@ Users may accidentally navigate to a non-existent dynamic route, such as a non-e
For presentational empty states (initial states with value propositions and actions), use the [EmptyStatePresentational](../fragments/empty-state-presentational) component from `ui-patterns`. This component provides a consistent structure with support for icons, titles, descriptions, and action buttons.
For other empty state scenarios (zero results, missing routes, etc), custom components may still be appropriate as the context and needs for each placement can differ significantly.
-
-## External references
-
-- [_Empty States_ on GitHub Primer](https://primer.style/product/ui-patterns/empty-states/)
diff --git a/apps/design-system/content/docs/ui-patterns/tables.mdx b/apps/design-system/content/docs/ui-patterns/tables.mdx
new file mode 100644
index 00000000000..84f4df000f5
--- /dev/null
+++ b/apps/design-system/content/docs/ui-patterns/tables.mdx
@@ -0,0 +1,83 @@
+---
+title: Tables
+description: Display structured data in a scannable, organized way.
+---
+
+Tables are a fundamental pattern for displaying structured data in rows and columns. They provide a scannable, organized way to present collections of related information, making it easy for users to compare values, identify patterns, and take action on specific items.
+
+The choice of table pattern depends on several factors: the complexity of the data, the level of interactivity required, the amount of data being displayed, and the context within the page layout.
+
+## Components
+
+There are three main table patterns, each suited to different use cases:
+
+- [Table](../components/table) is a low-level, presentational table component.
+- [Data Table](#data-table) builds on [Table](../components/table) and [TanStack Table](https://tanstack.com/table) to provide a feature-rich data browsing experience (sorting, filtering, pagination, etc.).
+- [Data Grid](#data-grid) is a separate grid implementation used for highly interactive, spreadsheet-like surfaces and very large datasets.
+
+Use Table when:
+
+- You need simple, static display
+- No filtering or complex behavior is needed
+
+Use Data Table when:
+
+- You need sorting, pagination, filtering, search, or row actions
+- You want TanStack-powered behavior with table semantics
+
+Use Data Grid when:
+
+- You need virtualization today
+- You need column resizing
+- You need spreadsheet-like editing
+
+Data Table and Data Grid are both _pattern components_: they are composed from primitives and built per use case. They are not available as standalone components.
+
+### Table
+
+[Table](../components/table) is designed for simple, static tabular data presentation. It is a presentational wrapper around the HTML `
` element. Use it when:
+
+- Displaying a fixed, known number of rows
+- The data is primarily read-only
+- Sort, filter, or search actions are not required or can be basic
+
+
+
+### Data Table
+
+Data Table is a pattern component and is not exposed as a Design System component. It is built on top of [Table](../components/table) and [TanStack Table](https://tanstack.com/table).
+
+Data Table extends Table with column definitions and row models (via TanStack) for complex sorting, filtering, and row actions. Use it when:
+
+- Displaying large datasets that require pagination
+- Users need to perform complex sort, filter, or search actions through the data
+- Row selection is required
+
+Data Table does not yet support virtualization, resizable columns, or advanced editors. These capabilities are planned as part of [consolidation with Data Grid](#future).
+
+
+
+As you can see from the above example, Data Table’s composition is heavily dependent on use case. We do not yet have a shared Design System component for this reason.
+
+Follow [Shadcn’s Data Table documentation](https://ui.shadcn.com/docs/components/data-table) for a complete guide on building upon the Data Table pattern for each specific use case. These patterns map closely to the approaches we follow internally.
+
+### Data Grid
+
+Data Grid is a pattern component and is not exposed as a Design System component. It is based on [React Data Grid](https://comcast.github.io/react-data-grid/#/CommonFeatures) and originally adopted for areas including Studio’s Table Editor, Query Performance, and other high-interaction surfaces.
+
+Use it only when you need virtualization, column resizing, or complex cell editing. Otherwise [Data Table](#data-table) is simpler and more flexible.
+
+
+
+## Future
+
+Data Table and Data Grid overlap significantly. We’re looking at consolidating these into one data table component, which will likely be improvements to Data Table given the numerous advantages of TanStack Table and difficulties extending React Data Grid.
+
+The likely direction is a single Data Table component built on TanStack Table, with
+
+- Virtualization
+- Resizable columns
+- Plug-in cell editors
+- Shared filtering/sorting utilities
+- Shared UI patterns (horizontal and vertical filter bars, date pickers, side panels)
+- Accessible, semantic HTML table markup
diff --git a/apps/design-system/content/docs/ui-patterns/ui-patterns.mdx b/apps/design-system/content/docs/ui-patterns/ui-patterns.mdx
new file mode 100644
index 00000000000..b89667e7750
--- /dev/null
+++ b/apps/design-system/content/docs/ui-patterns/ui-patterns.mdx
@@ -0,0 +1,16 @@
+---
+title: UI patterns
+description: Higher-level guidance on how to compose components together to solve common interface problems.
+---
+
+UI patterns are reusable design solutions that combine multiple components from our design system to address common interface challenges. Unlike atom components (basic building blocks like buttons and inputs) or fragment components (pre-built composite components), UI patterns provide guidelines and best practices for structuring entire interface sections.
+
+These patterns help ensure consistency across Supabase products by establishing standard approaches for:
+
+- **[Charts](/docs/ui-patterns/charts)**: Visualizing data consistently using standardized chart types and styling.
+- **[Empty States](/docs/ui-patterns/empty-states)**: Communicating the absence of data and guiding users toward meaningful actions.
+- **[Forms](/docs/ui-patterns/forms)**: Building cohesive form experiences in both page layouts and side panels.
+- **[Layout](/docs/ui-patterns/layout)**: Creating consistent page structures with proper spacing, max-widths, and content organization.
+- **[Navigation](/docs/ui-patterns/navigation)**: Organizing complex hierarchical navigation systems across multiple products and contexts.
+
+UI patterns may incorporate external libraries (such as `react-markdown`, `reactflow`, `recharts`, etc) or compose various components from the `ui` package. They serve as blueprints for solving recurring design problems, ensuring that similar features across the application follow the same structural and interaction patterns.
diff --git a/apps/design-system/contentlayer.config.js b/apps/design-system/contentlayer.config.js
index edc30b91b1d..4d12b6a0886 100644
--- a/apps/design-system/contentlayer.config.js
+++ b/apps/design-system/contentlayer.config.js
@@ -53,6 +53,9 @@ const NestedProperties = defineNestedType(() => ({
reactAccessibleTreeview: {
type: 'boolean',
},
+ recharts: {
+ type: 'boolean',
+ },
},
}))
diff --git a/apps/design-system/eslint.config.cjs b/apps/design-system/eslint.config.cjs
index fec3ac9b3ab..e425bf679a9 100644
--- a/apps/design-system/eslint.config.cjs
+++ b/apps/design-system/eslint.config.cjs
@@ -1,4 +1,12 @@
const { defineConfig } = require('eslint/config')
const supabaseConfig = require('eslint-config-supabase/next')
-module.exports = defineConfig([supabaseConfig])
+module.exports = defineConfig([
+ supabaseConfig,
+ {
+ files: ['registry/**/*.tsx', '__registry__/**/*.tsx'],
+ rules: {
+ 'no-restricted-exports': 'off',
+ },
+ },
+])
diff --git a/apps/design-system/lib/rehype-component.ts b/apps/design-system/lib/rehype-component.ts
index adc038328ea..111fee0b42d 100644
--- a/apps/design-system/lib/rehype-component.ts
+++ b/apps/design-system/lib/rehype-component.ts
@@ -7,10 +7,6 @@ import { visit } from 'unist-util-visit'
import { Index } from '../__registry__'
import { styles } from '../registry/styles'
-// import { parse } from 'react-docgen'
-
-// import * as reactDocgenTypescript from 'react-docgen-typescript'
-
// import { Column, IColumnProps } from './sample-component'
import React from 'react' // ComponentType
@@ -38,61 +34,6 @@ export function rehypeComponent() {
type?: string
}) || {}
- // console.log(srcPath, componentName)
-
- // inspectComponentProps(Column)
-
- // console.log('NEW NODE: ', node.name)
-
- // if (node.name === 'ComponentProps') {
- // // Parse a file for docgen info
- // const options = {
- // // savePropValueAsString: true,
- // }
-
- // // const parser = reactDocgenTypescript.parse('./sample-component.tsx', options)
-
- // // console.log('PARSER', parser)
-
- // const code = `
- // /** My first component */
- // export default ({ name, title }: {
- // /** My first component */
- // name: string,
- // /** My first component */
- // title: string
- // }) =>
+
+
+
+ Total Requests
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
+
+
+
+ Standard Bar Chart
+
+
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
+
+
+
+
+
+
+
+ Standard Line Chart
+
+
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
+
+
+
+ Standard Bar Chart
+
+
+ }
+ title="No data to show"
+ description="It may take up to 24 hours for data to refresh"
+ />
+ }
+ loadingState={}
+ >
+
- Table name
- Date created
-
+ Name
+ Created
+ Updated
diff --git a/apps/design-system/registry/default/example/field-checkbox.tsx b/apps/design-system/registry/default/example/field-checkbox.tsx
new file mode 100644
index 00000000000..67d21658b65
--- /dev/null
+++ b/apps/design-system/registry/default/example/field-checkbox.tsx
@@ -0,0 +1,67 @@
+import { Checkbox_Shadcn_ as Checkbox } from 'ui'
+import {
+ Field,
+ FieldContent,
+ FieldDescription,
+ FieldGroup,
+ FieldLabel,
+ FieldLegend,
+ FieldSeparator,
+ FieldSet,
+} from 'ui/src/components/shadcn/ui/field'
+
+export default function FieldCheckbox() {
+ return (
+
+
+
+
+
+
+
+
+ Sync Desktop & Documents folders
+
+
+ Your Desktop & Documents folders are being synced with iCloud Drive. You can access
+ them from other devices.
+
+
+
+
+
+
+ Price Range
+
+ Set your budget range ($
+ {value[0]} -{' '}
+ {value[1]}).
+
+
+
+
+ )
+}
diff --git a/apps/design-system/registry/default/example/field-switch.tsx b/apps/design-system/registry/default/example/field-switch.tsx
new file mode 100644
index 00000000000..6ebd246f922
--- /dev/null
+++ b/apps/design-system/registry/default/example/field-switch.tsx
@@ -0,0 +1,24 @@
+import { Switch } from 'ui'
+import {
+ Field,
+ FieldContent,
+ FieldLabel,
+ FieldDescription,
+} from 'ui/src/components/shadcn/ui/field'
+
+export default function FieldSwitch() {
+ return (
+
+
+
+ Multi-factor authentication
+
+ Enable multi-factor authentication. If you do not have a two-factor device, you can use
+ a one-time code sent to your email.
+
+
+
+
+
- Future audit logs will only appear in the project's{' '}
-
- auth logs
-
- . You are responsible for backing up, copying, or migrating existing data from
- the {AUDIT_LOG_ENTRIES_TABLE} table if needed.
-
-
+ description={
+
+ Future audit logs will only appear in the project’s{' '}
+
+ auth logs
+
+ . You are responsible for backing up, copying, or migrating existing data
+ from the{' '}
+
+ {AUDIT_LOG_ENTRIES_TABLE}
+ {' '}
+ table if needed.
+
{isPubliclyReadableWritable
- ? "Anyone with your project's anonymous key can read, modify, or delete your data."
+ ? 'Anyone with your project’s anonymous key can read, modify, or delete your data.'
: 'No data will be selectable via Supabase APIs because RLS is enabled but no policies have been created yet.'}
-
- While most credit card payments get processed instantly, some Indian credit card
- providers may take up to 72 hours. Your card issuer has neither confirmed nor denied
- the payment and we have to wait until the card issuer processed the payment.
+
+ While most credit card payments get processed instantly, some Indian card providers
+ may take up to 72 hours to process payments. We’re still waiting for your card
+ provider to process this payment.
-
- If you run into this, we recommend{' '}
+
+ We recommend proactively{' '}
topping up your credits
{' '}
- in advance to avoid running into this in the future.
+ to avoid this issue in the future.
) : paymentAttempted ? (
-
+
We were not able to collect the payment. Make sure you have a valid payment method and
enough funds. Outstanding invoices may cause restrictions. You can manually pay the
- invoice using the "Pay Now" button.
+ invoice using the “Pay now” button.
) : (
-
- The invoice will soon be charged for. In case you pay via invoice instead of card,
- please make sure to make the payment in a timely manner. You can also pay the invoice
- using your card now using the "Pay Now" button.
+
+ The invoice will soon be charged for. Please make sure to pay in a timely manner,
+ especially if you pay via invoice instead of card. You can pay the invoice using your
+ card using the “Pay now” button.
))}
{status === InvoiceStatus.PAID && (
-
- The invoice has been paid successfully. No action is required on your side.
-
+
The invoice has been paid successfully. No further action is required on your side.
)}
{status === InvoiceStatus.VOID && (
-
- This invoice has been forgiven. No action is required on your side.
-
+
This invoice has been forgiven. No further action is required on your side.