---
name: rebase-customize-admin
description: How to customize the Rebase admin panel by writing React components — singletons and settings pages, per-user settings, dashboards, custom pages, master-detail pages, approval queues, bulk actions, toolbar buttons, record buttons and tabs, new collection view modes (calendar, map, gallery), custom fields, replacing the login screen or any built-in part, and rebranding it (brand colour, fonts, corners, surfaces, logo, light/dark mode). Use this skill whenever a user asks for something the admin does not do out of the box, before reaching for configuration options.
---

# Customizing the Rebase admin

The admin is built from parts you can use yourself. **Customizing it means
writing an ordinary React component and putting it in a place.** Do not look
for a configuration flag for the feature (there is no `singleton: true`, no
`calendar` view type, no `bulkEdit` option) — build it.

There are three things to know:

1. **Building blocks** you render: `CollectionPanel`, `RecordForm`,
   `FormField`, `RecordDetail`, `FieldValue`, `CollectionsProvider`,
   `RebaseAuthGate` (`@rebasepro/cms`), `LoginView`
   (`@rebasepro/app`) and the UI kit (`@rebasepro/ui`: `SplitView` for
   master-detail, `KpiGrid` / `KpiTile` / `ChartCard` / `BarChart` /
   `TimeSeriesChart` for figures, and `Button`, `Card`, `Typography`,
   `TextField`, `Select`, `Chip`, `Container`, …).
   `CollectionPanel` takes data and components, not flags: `fields` (the
   fields it shows, in order), `toolbar` (`null`, or a `CollectionToolbar`
   composed of `CollectionSearchBar`, `CollectionFiltersButton`,
   `CollectionViewModeToggle`, `CollectionAddButton`), `onRowClick` (the
   row, as `useRows` reads it, instead of opening it), `viewMode`, `highlightedIds`,
   `collectionOverrides`, `sort`, `limit`, `title`.
2. **Hooks**: `useRows`, `useRow`, `useRowCount`, `useAggregate`,
   `useRowWrites` for data, `useRebaseContext().data` for the same rows outside
   React state, then `useAuthController`, `useSnackbarController`,
   `usePermissions` (`@rebasepro/app`); `useSidePanel`, `useUrlController`,
   `useCollectionRegistryController`, `resolveSelection` (`@rebasepro/cms`).
3. **Places**: a page (`<RebaseCMS views>`), a collection view mode
   (`collectionViews` + `customViews` in the table's `customizeTable`), a
   toolbar button (`Actions`), a record button (`entityActions`), a record tab
   (`entityViews`), a field (`fields.<key>.Field` / `Preview`) — all options of
   `customizeTable<typeof table>("slug", { … })` in `frontend/src/cms/`,
   components imported by value — something
   beside a built-in part (`<Rebase slots>`), or a replacement for a built-in
   part (`<Rebase components>`, `wrap: true` to keep the original inside).

## Changing the look is tokens, not components

A request to rebrand the admin (brand colour, fonts, corners, a warmer dark
theme, the logo) is **not** a component job. Override tokens in
`frontend/src/index.css`, after the imports:

```css
@theme {
    --color-primary: #16a34a;   /* buttons, links, focus, charts, selection */
    --font-sans: "Manrope Variable", ui-sans-serif, system-ui, sans-serif;
    --font-headers: "Manrope Variable", ui-sans-serif, system-ui, sans-serif;
    --radius-lg: 4px;           /* controls, menus */
    --radius-xl: 6px;           /* cards, dialogs */
}
.dark { --surface-frame: #0d0b09; --surface-card: #1b1814; }  /* role surfaces: :root for light, .dark for dark */
```

`--color-primary-light/-dark/-bg` and `--color-on-primary` (black or white
ink, whichever reads on the primary) are derived; do not set them unless
asked. The logo and name are `<RebaseShell title logo logoDark>`; the same
logo shows on the sign-in screen. Forcing one theme is a `modeController` on
`<Rebase>` plus `class="dark"` on `<html>`. Never write the brand colour as a
literal in a component: use `bg-primary` / `text-primary`. Reference:
`/docs/frontend/theming`.

## Start from a recipe

Tested recipes ship inside the installed package. **Read the matching one
before writing anything** — it uses the APIs of the version the project has:

```
node_modules/@rebasepro/cms/recipes/README.md         ← the full reference
node_modules/@rebasepro/cms/recipes/site-settings.tsx  ← singleton / settings page
node_modules/@rebasepro/cms/recipes/my-preferences.tsx ← per-user settings (record keyed by uid)
node_modules/@rebasepro/cms/recipes/bulk-set-status.tsx ← toolbar action over selected rows
node_modules/@rebasepro/cms/recipes/approval-queue.tsx ← Approve / Reject on every row and card, a count of what is left
node_modules/@rebasepro/cms/recipes/master-detail.tsx  ← a list beside the picked record's form (SplitView)
node_modules/@rebasepro/cms/recipes/calendar-view.tsx  ← a new collection view mode
node_modules/@rebasepro/cms/recipes/orders-dashboard.tsx ← KPI tile and bar chart over a count and an aggregate
node_modules/@rebasepro/cms/recipes/custom-login.tsx   ← replacing a built-in screen
```

Copy the closest recipe into the project's frontend, rename, adapt. Recipes
import only package entry points, so they compile as copied.

## Rules

- **A singleton is a normal table + a page with `RecordForm` at a
  fixed `id`.** The form creates the record under that id on first save;
  nothing needs seeding. Hide its collection from navigation with
  `hideFromNavigation: true` in the table's `customizeTable`.
- **A form showing some fields, or laid out your way, is `RecordForm`
  with `fields` or `FormField` children** (0.29+) — not a form of your own.
  `fields={["name", "status"]}` shows those, in that order.
  `<RecordForm collection="orders" id={id}><div>…<FormField name="status"/>…</div></RecordForm>`
  is your own JSX; each `FormField` draws one field with the form's label,
  size and rules. `compact` is the dense form for a side card. The form
  validates only the fields it shows, and refuses to create a record (naming the
  fields) when a required field without a default is left out — show it, or
  give it a default. `collectionOverrides` changes the collection for that form
  only.
- **A record to read, not edit, is `RecordDetail`** (0.29+), with the same
  `collection`, `id`, `fields` and `collectionOverrides` as the form. It
  hides what the form hides: a field a `conditions.hidden` rule hides for that
  record, or one the user may not read.
- **One value in your own JSX is `<FieldValue collection="orders"
  field="status" value={order.status}/>`** (0.29+), not a hand-formatted
  string. It takes the value as the server sends it — a belongsTo as its
  foreign key, `field="customer" value={order.customerId}` — and draws the enum
  chip, the date in its timezone or the relation's title as the admin does. The
  collection must be registered above it.
- **Read with `useRows` / `useRow` / `useRowCount` / `useAggregate`, write with
  `useRowWrites`** (0.29+). Their rows are the server's rows — exactly the
  table's columns (`row.id` only where the table has an `id` column), dates
  as ISO strings, a belongsTo as its foreign-key column (`customerId`), and a
  relation the admin loaded nested under its name (`row.customer`, exactly the
  customer's columns), as REST's `include` returns it — the same shape as `client.data`, `context.data`,
  `resolveSelection({ selection, data: context.data, collection })`,
  `CollectionPanel`'s `onRowClick`, a view mode's `tableController.rows`, a
  collection action's `selectionController.selection` and what
  `browserCallbacks` and `entityActions` are handed. The record's id comes
  beside its row, as a string: `id` beside a `row`, `ids` beside `rows` at the
  same positions (`tableController.ids[i]`; `resolveSelection` returns
  `{ rows, ids }`). Write and open with it, never `String(row.id)` — a
  table keyed by another column has no `row.id`. A write is the record
  form's save: `browserCallbacks`, then the server's table hooks and row-level
  security, and every view of the collection reads it again; a write through
  `context.data` is the same. An `Entity` (`{ id, path, values }`) is only what
  a copy of one of the admin's own parts is handed. Don't call `fetch` on the
  REST API from admin code.
- **A button on every row and card of one panel is its `rowActions`**:
  `rowActions={(row, id) => <Button size="small" onClick={…}>Ship</Button>}`
  — the table's last column, beside the actions on a list row, a card and a
  kanban card. An action every view of the collection offers is an
  `entityActions` entry with `collapsed: false` in the table's `customizeTable`. Not a column of your own.
- **A list beside the picked record is `SplitView`** with a `CollectionPanel`
  (`onRowClick`, `highlightedIds`) as `master` and an `RecordForm` or
  `RecordDetail` as `detail`. It lays out by its container's width, so it
  drills down in a narrow frame by itself; give its parent a height.
- **Draw with `@rebasepro/ui`** so the page matches the admin (see the
  `rebase-design-language` skill). For KPIs and charts, use the metric blocks
  from `@rebasepro/ui` (`KpiGrid`, `KpiTile`, `ChartCard`, `BarChart`,
  `TimeSeriesChart`) and let the database compute the numbers: `useRowCount`
  and `useAggregate` (`count`/`sum`/`avg`/`min`/`max`, grouped), never a
  reduce over rows read into the browser. For figures one aggregate cannot
  express, `useInsightData` from `@rebasepro/plugin-insights` runs SQL on the
  server — the `rebase-dashboards` skill is the whole method.
- **When a built-in part almost fits, override or wrap it** with
  `<Rebase components={{ "<Name>": { Component, wrap? } }}>`. The names are
  `OverridableComponentName` in `@rebasepro/cms-types`. Prefer `wrap: true`:
  you keep the original inside yours and still get its fixes on upgrade. When
  wrapping is not enough, copy the original and change the copy — see
  "Copying a built-in part" below. The props your component receives are the
  original's.
- **Server-side behaviour (validation that must hold, derived fields, side
  effects) belongs in the table's `hooks` (or a column's `.transform()`) in
  `backend/schema/`**, not only in a component — see the `rebase-tables`
  skill.

## Copying a built-in part

The npm packages ship `dist`, not source. The source of a part, at the version
the project has, is in https://github.com/rebasepro/rebase at tag
`v<installed version>` (read the version from `node_modules/@rebasepro/cms/package.json`).
The table and the copyability below are 0.26+; at an older tag most parts
import internals, and a file may sit elsewhere — find it by its
`useComponentOverride("<Name>", Default)` call.


| Override name | Default component | Source file |
|---|---|---|
| `Auth.LoginView` | `LoginView` | `packages/app/src/components/LoginView/LoginView.tsx` |
| `Collection.Actions` | `CollectionViewActions` | `packages/cms/src/components/CollectionViewBinding/CollectionViewActions.tsx` |
| `Collection.Card` | `EntityCardBinding` | `packages/cms/src/components/CollectionViewBinding/EntityCardBinding.tsx` |
| `Collection.EmptyState` | `DefaultCollectionEmptyState` | `packages/cms/src/components/CollectionViewBinding/DefaultCollectionEmptyState.tsx` |
| `Collection.FilterField` | `DefaultFilterField` | `packages/cms/src/components/SelectableTable/filters/FilterFieldBinding.tsx` |
| `Collection.Table` | `CollectionTableBinding` | `packages/cms/src/components/CollectionTableBinding/CollectionTableBinding.tsx` |
| `Collection.View` | `CollectionViewBinding` | `packages/cms/src/components/CollectionViewBinding/CollectionViewBinding.tsx` |
| `DetailView` | `DetailViewBinding` | `packages/cms/src/components/DetailViewBinding.tsx` |
| `EditView.FormActions` | `EditFormActions` | `packages/cms/src/components/EditFormActions.tsx` |
| `Entity.Form` | `EntityFormBinding` | `packages/cms/src/form/EntityFormBinding.tsx` |
| `Entity.MissingReference` | `DefaultMissingReference` | `packages/cms/src/components/DefaultMissingReference.tsx` |
| `Entity.SidePanel` | `SidePanelBinding` | `packages/cms/src/components/SidePanelBinding.tsx` |
| `EntityPreview` | `EntityPreviewBinding` | `packages/cms/src/components/EntityPreviewBinding.tsx` |
| `HomePage` | `ContentHomePage` | `packages/cms/src/components/HomePage/ContentHomePage.tsx` |
| `HomePage.CollectionCard` | `NavigationCardBinding` | `packages/cms/src/components/HomePage/NavigationCardBinding.tsx` |
| `Shell.AppBar` | `DefaultAppBar` | `packages/cms/src/components/DefaultAppBar.tsx` |
| `Shell.Drawer` | `Drawer` | `packages/cms/src/components/app/Drawer.tsx` |
| `Shell.DrawerNavigationGroup` | `DrawerNavigationGroup` | `packages/cms/src/components/DrawerNavigationGroup.tsx` |
| `Shell.DrawerNavigationItem` | `DrawerNavigationItem` | `packages/cms/src/components/DrawerNavigationItem.tsx` |

`Shell.Drawer`'s default is a thin wrapper: the drawer itself is
`DefaultDrawer`, in `packages/cms/src/components/DefaultDrawer.tsx`, and copies
the same way.

To copy one: put the file in the project's frontend, rewrite each relative
import (`../hooks/…`, `./drawer_expansion`, …) to `@rebasepro/cms` or
`@rebasepro/app` — everything the file imports is exported from one of them —
change what you came to change, and register the copy under its name in
`<Rebase components>` (or `components` in a table's `customizeTable` for the
collection-scoped names: `Collection.*`, `Entity.*`, `EditView.FormActions`,
`DetailView` and `EntityPreview`). Keep the copy small: change the part, not its neighbours.

Three parts are deliberately **not** copyable, because what they import are
internals of a composition, not building blocks. Do not try to export or
reimplement those internals; customize around them:

- **`Collection.View`** — every view mode with inline editing, the popup field
  editor, the delete dialog and the view mode's URL state. Replace one of its
  parts instead (`Collection.Table`, `Collection.Card`, `Collection.Actions`,
  `Collection.EmptyState`, all copyable), add a view mode with
  `collectionViews`, or `wrap: true`.
- **`DetailView`** — the record view: identity bar, tabs, inspector, split-list
  buttons, around tab ids that are URL values. Use `entityViews`,
  `entityActions`, the `form.*` slots, or the copyable `Entity.Form` and
  `EditView.FormActions`.
- **`HomePage`** — copyable except its drag-and-drop reordering. A home page of
  your own composes `NavigationGroup`, `NavigationCardBinding` and
  `FavouritesView` (`@rebasepro/cms`) over
  `useNavigationStateController().topLevelNavigation`; to add to the stock one,
  use the `home.cards` slot.

