Prepared Docs

Overview

CrudPage from @prepared911/ui-blocks is the standard assembly for list-first admin surfaces: a page header for route identity, a toolbar for search or filters plus the page’s primary CTA, and a body region for DataTable (or a list plus detail pane). It matches the mental model of “DataTable paired with a CTA button and page header” in one predictable vertical stack.

When to use

Supervisor or admin routes that center on a sortable, filterable table with a clear create or import action.
Settings hubs where the title and description stay fixed while the grid scrolls.
QA-style queues with a filter bar and server-driven pagination in the body.

When not to use

Detail-only or dashboard pages where a table is not the primary surface—use PageHeader alone or a bespoke layout.
Modal or drawer bodies—use their built-in headers, not a full page shell.
Full-screen immersive flows—use TakeoverPage.

Anatomy

Regions render in a fixed order regardless of how you order children in JSX:

CrudPageHeader: wraps PageHeader without the actions prop; primary CTAs belong in the toolbar instead.
CrudPageAlert (optional): persistent slot between header and toolbar for Callout, Banner, or similar.
CrudPageToolbar: DataTableToolbar from @prepared911/ui-data-table: filters, applied chips, and actions (typically one primary button).
Body: CrudPageBody or any other children; loose children are auto-wrapped in a column flex body when CrudPageBody is omitted.

See API and Development for how children are partitioned into slots.

Variants

Concern	Choice
Chrome	`CrudPageVariant.Default` inherits surrounding page chrome. `CrudPageVariant.Card` adds background, border, and radius for embedding in modals, drawers, or nested dashboards.
Body layout	Default: direct children (e.g. `DataTable`) are wrapped in a column flex with `gap`. Use `CrudPageBody` when you need a row layout (list + detail) or a custom `gap` / `flexDirection`; then the default wrapper is skipped.
Child order	`CrudPageHeader`, `CrudPageAlert`, and `CrudPageToolbar` are collected and rendered in the slot order above; you can still write them in any order in JSX.

Behavior and states

The root uses flex growth and overflow: hidden so the body region owns vertical scroll while header, alert, and toolbar stay visible.
Pair CrudPageToolbar with Filter and useFilteredData from @prepared911/ui-data-table for local search; pass manualPagination, pages, and onPageChange on DataTable for server-style pages.
Use CrudPageAlert for notices that must stay above the table (sync paused, read-only integration, maintenance).

Best practices

Keep one primary CTA in CrudPageToolbar.actions (create, upload, export).
Put breadcrumb and count on CrudPageHeader; keep filter chips and search in the toolbar.
Use CrudPageBody when composing a table beside a drawer or secondary pane so direction and overflow stay explicit.

Don’t

Don’t add a second row of global actions on CrudPageHeader—it omits actions by design.
Don’t put page-critical warnings only inside the scrolling table—use CrudPageAlert or a Callout in the alert slot.

Accessibility

Keyboard and heading behavior follow PageHeader, DataTableToolbar, and DataTable. See Accessibility for this block.

Forms / Accessibility

Crud Page / API and Development

Overview

When to use

Supervisor or admin routes that center on a sortable, filterable table with a clear create or import action.
Settings hubs where the title and description stay fixed while the grid scrolls.
QA-style queues with a filter bar and server-driven pagination in the body.

When not to use

Detail-only or dashboard pages where a table is not the primary surface—use PageHeader alone or a bespoke layout.
Modal or drawer bodies—use their built-in headers, not a full page shell.
Full-screen immersive flows—use TakeoverPage.

Anatomy

Regions render in a fixed order regardless of how you order children in JSX:

CrudPageHeader: wraps PageHeader without the actions prop; primary CTAs belong in the toolbar instead.
CrudPageAlert (optional): persistent slot between header and toolbar for Callout, Banner, or similar.
CrudPageToolbar: DataTableToolbar from @prepared911/ui-data-table: filters, applied chips, and actions (typically one primary button).
Body: CrudPageBody or any other children; loose children are auto-wrapped in a column flex body when CrudPageBody is omitted.

See API and Development for how children are partitioned into slots.

Variants

Concern	Choice
Chrome	`CrudPageVariant.Default` inherits surrounding page chrome. `CrudPageVariant.Card` adds background, border, and radius for embedding in modals, drawers, or nested dashboards.
Body layout	Default: direct children (e.g. `DataTable`) are wrapped in a column flex with `gap`. Use `CrudPageBody` when you need a row layout (list + detail) or a custom `gap` / `flexDirection`; then the default wrapper is skipped.
Child order	`CrudPageHeader`, `CrudPageAlert`, and `CrudPageToolbar` are collected and rendered in the slot order above; you can still write them in any order in JSX.

Behavior and states

The root uses flex growth and overflow: hidden so the body region owns vertical scroll while header, alert, and toolbar stay visible.
Pair CrudPageToolbar with Filter and useFilteredData from @prepared911/ui-data-table for local search; pass manualPagination, pages, and onPageChange on DataTable for server-style pages.
Use CrudPageAlert for notices that must stay above the table (sync paused, read-only integration, maintenance).

Best practices

Keep one primary CTA in CrudPageToolbar.actions (create, upload, export).
Put breadcrumb and count on CrudPageHeader; keep filter chips and search in the toolbar.
Use CrudPageBody when composing a table beside a drawer or secondary pane so direction and overflow stay explicit.

Don’t

Don’t add a second row of global actions on CrudPageHeader—it omits actions by design.
Don’t put page-critical warnings only inside the scrolling table—use CrudPageAlert or a Callout in the alert slot.