> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dezerx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin pages

> Build a custom admin screen from the Admin Modern kit so it matches the rest of the admin and follows its theme.

![A custom admin page built from AdminLayout, PageHeader, Stat, DataTable and Panel](https://mintcdn.com/dezerx/dVNBM3sq4VCh7CKa/public/extensions/admin-pages/top.webp?fit=max\&auto=format\&n=dVNBM3sq4VCh7CKa\&q=85\&s=f893da5c689b2376a4c30a1f694a53c6)

Most modules do not need this. If a field list is enough, use the [generated settings page](https://docs.dezerx.com/extensions/tutorials/module-json.md#settings-page-without-react). Write a custom page for tables, dashboards, editors and anything with its own workflow.

## Build it

**1. Render a page name from a controller**

```php theme={null}
return Inertia::render('LoyaltyRewards/Admin/Settings', ['settings' => $settings]);
```

Put the route in `routes/settings.php` and declare its permission in `module.json`, see [module.json and settings](https://docs.dezerx.com/extensions/tutorials/module-json.md#admin-permissions).

**2. Register the page**

```ts resources/js/register.ts theme={null}
import { registerModulePages } from '../../../../../resources/js/modulePages';

registerModulePages({
    'LoyaltyRewards/Admin/Settings': () => import('./Pages/Admin/Settings.tsx'),
});
```

**3. Write the page**

Wrap it in `AdminLayout` and build from the kit, see the example below.

**4. Build the frontend**

```bash theme={null}
npm run build
```

## A small complete example

```tsx Pages/Admin/Settings.tsx theme={null}
import RichTextEditor from '@/components/editor/RichTextEditor';
import AdminLayout from '@/layouts/AdminLayout';
import { Panel } from '@/pages/admin-themes/admin-modern/components/Panel';
import { Field, SwitchRow } from '@/pages/admin-themes/admin-modern/components/form';
import { PageHeader } from '@/pages/admin-themes/admin-modern/components/ui';
import { useUnsavedGuard } from '@/pages/admin-themes/admin-modern/lib/use-unsaved-guard';
import '@/pages/admin-themes/admin-modern/theme.css';
import { useForm } from '@inertiajs/react';

interface Props {
    settings: { enabled: boolean; points_per_order: number; terms: string };
}

export default function Settings({ settings }: Props) {
    const form = useForm(settings);
    const save = () => form.put('/admin/loyalty-rewards/settings');

    useUnsavedGuard({ dirty: form.isDirty, onSave: save, busy: form.processing });

    return (
        <AdminLayout title="Loyalty rewards">
            <PageHeader
                title="Loyalty rewards"
                description="Points customers earn on every paid order."
                actions={
                    <button type="button" className="am-button am-button-primary" disabled={form.processing || !form.isDirty} onClick={save}>
                        Save changes
                    </button>
                }
            />

            <Panel title="Points" description="How customers earn points.">
                <div className="grid gap-4">
                    <SwitchRow label="Enabled" checked={form.data.enabled} onChange={(value) => form.setData('enabled', value)} />
                    <Field label="Points per order" error={form.errors.points_per_order}>
                        <input
                            type="number"
                            value={form.data.points_per_order}
                            onChange={(event) => form.setData('points_per_order', Number(event.target.value))}
                        />
                    </Field>
                    <RichTextEditor
                        label="Terms"
                        value={form.data.terms}
                        onChange={(markdown) => form.setData('terms', markdown)}
                        minHeight={200}
                    />
                </div>
            </Panel>
        </AdminLayout>
    );
}
```

```php Controller theme={null}
public function update(Request $request)
{
    $data = $request->validate([
        'enabled' => ['boolean'],
        'points_per_order' => ['integer', 'min:0'],
        'terms' => ['nullable', 'string'],
    ]);

    LoyaltySetting::saveAll($data);

    return back();
}
```

`AdminLayout` gives the page the Admin Modern shell: sidebar, topbar and breadcrumbs.

## The kit

Import from `@/pages/admin-themes/admin-modern/components/`.

| Piece | File | Use |
| - | - | - |
| `PageHeader` | `ui` | Title, description and action buttons |
| `Stat`, `StatGroup` | `ui` | Number tiles |
| `FilterBar`, `SearchField`, `FilterSelect`, `DateRangeFilter` | `ui` | Search and filters with removable chips |
| `DataTable`, `Pagination`, `EmptyState` | `ui` | Lists. Pass `page` from a Laravel paginator |
| `Dialog`, `StatusText` | `ui` | Modals and status labels |
| `Panel` | `Panel` | A titled card with an optional action and footer |
| `Field`, `Group`, `Segmented`, `SwitchRow`, `MoneyInput`, `FormSection` | `form` | Form building blocks |
| `ConfirmDialog`, `Notice`, `IconAction` | `actions` | Confirmations, banners and row actions |

Buttons use `am-button` with `am-button-primary`, `am-button-quiet`, `am-button-danger` or `am-button-critical`. A plain `<input>`, `<select>` or `<textarea>` inside `Field` is styled for you.

> [accordion] Theme colours and corner radius
>
> The page inherits its look from `theme.css`. Use its variables instead of fixed colours: `--am-ink`, `--am-muted-ink`, `--am-surface`, `--am-hairline`, `--am-accent`, `--am-good`, `--am-warning` and `--am-critical`.
>
> Admins change the palette on the Colors page in the admin, and the corner roundness with the `ui_corner_radius` setting. Both flow through these variables, so anything built from the kit follows along. Hard coded hex colours and pixel radii will not.

## The RichTextEditor

`@/components/editor/RichTextEditor` is the Markdown editor used by News, Blog, the knowledge base and custom pages. It edits and returns Markdown, with a bubble menu, a slash menu, tables, task lists and image upload.

```tsx theme={null}
<RichTextEditor
    label="Article content"
    value={data.content}
    onChange={(markdown) => setData('content', markdown)}
    onUploadImage={async (file) => uploadAndReturnUrl(file)}
    minHeight={360}
    maxHeight={720}
/>
```

Props: `value`, `onChange`, `placeholder`, `label`, `maxLength`, `error`, `disabled`, `draftKey` (keeps a local draft), `attachments`, `actions`, `minHeight`, `maxHeight`, `onEditorReady` and `onUploadImage`. Render saved Markdown on the public side with `@/components/MarkdownRenderer`.

> [!WARNING]
>
> Only packages in core's `package.json` exist. Do not add your own editor or chart library. The module's `package.json` is never installed.

## Worth reading

> [card] GDPRCompliance
>
> Dashboard, tables, filters, dialogs and a RichTextEditor form.

> [card] Affiliates
>
> Stats, tables and settings built with `Field` and `Panel`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.