Composables

Forty-three composables and two directives. Every signature on these pages was read off the source file, not the older documentation.

They sit on forty pages: three of them — useShortcutRegistry, useShortcutCheatSheet and useTourController — are documented beside the sibling they share a module with.

Each page follows the same shape: what it is, the import, the real signature, a table of everything it returns, a complete example, the behavior worth knowing, and where to go next. Where a composable has a visible effect, the example on its page is running.

Core

Configuration, the theme engine and language.

Composable	What it does
useConfig	The store that owns the whole SmartAdminConfig, persisted.
usePageConfig	Per-page overrides, without writing to the store.
useTheme	Brand colors, their generated ramps, and dark mode.
useThemeProvider	The tenant palette at startup, cache first.
useTypography	The type scale, as three presets.
useDensity	The spacing preset.
useFonts	Loading web fonts on demand.
useChartTheme	Chart colors, re-resolved when the theme changes.
useLocale	Switching language, and the nine shipped locales.
useDirection	dir and lang on the document.

Forms and data

The schema engine and everything built on it.

Composable	What it does
useSchema	One field list, reshaped into form fields, columns, groups and Zod.
useFormSurface	What kind of container a form is rendering inside.
useCrud	Typed list, create, update and delete with pagination and toasts.
useRouteRecord	A detail page's record, reloaded when the id changes, with a not-found state.
useFormDraft	Auto-saving a form in progress.
useFormDirty	Warning before unsaved changes are lost.
useSaEditor	A Tiptap editor with the template's extensions.

Auth and errors

Composable	What it does
useAuth	Login, logout, session refresh, and the boot-time rehydrate.
usePermissions	can and cannot, over CASL.
useNavPermission	The menu's own gates, which treat guests differently.
useApiError	What each HTTP status looks like to the reader.

Productivity

The command palette, shortcuts, the tour and the shell's own drawers.

Composable	What it does
useCommandRegistry	Every command the palette can run.
useCommandPalette	Opening and closing it.
useShortcuts	Key bindings, and the registry behind the cheat sheet.
usePageShortcuts	The same, scoped to one page.
useTour	The guided tour.
usePinnedPages	The reader's own shortlist of pages.
useResponsivePreview	The device preview's state and catalog.
useCustomizer	The theme drawer's open state.

Infrastructure

Composable	What it does
useConfirm	await confirm(...), from anywhere.
useFileUpload	Selecting, validating and uploading files.
useExport	CSV, Excel and PDF, lazy-loaded.
useNotifications	The store behind the navbar bell.
useRealtimeNotifications	An optional live feed.
useActivityLog	Writing audit entries.
useConnectivity	Online, offline, and just reconnected.
useSubscription	Plans, billing cycle and usage.
useAvailableHeight	A real height for a pane that scrolls inside itself.
useLayout	Which of the six shells renders.
useResponsiveLayout	What "mobile" means, and the drawer.

Directives

Directive	What it does
v-copy	Click an element to copy it.
v-permission	Hide an element the user may not act on.

Both are registered globally in a project built from the template.

Conventions

• Imports are absolute, through the template's aliases:

  import { useConfig } from '@core/config/useConfig'
  import { useConfirm } from '@shared/composables/useConfirm'
  import { useLayout } from '@/layouts/useLayout'

• A lot of these are singletons. Module-scope state, not per-caller state, so the navbar and a widget three routes away read the same value. Each page says so where it matters.

• readonly means write through the functions beside it. A returned ref wrapped in readonly has setters alongside it; that is the supported path.

• Several persist to localStorage, all under an sa- prefix: sa-config, sa-color-mode, sa-tenant-theme, sa-notifications, sa-pinned, sa-tours, sa-recent-commands, and one sa-draft:{key} per form.

• Anything that touches the DOM checks for it first, so a setter called before mount is a no-op rather than a crash. The two Pinia stores are the exception: they name localStorage when their module is evaluated, so they are not safe to import in a server render.

Where to go next

• Components — what these drive.
• Schema — the field list behind the forms and tables.
• Global config — every config key.
• Architecture — where each of these lives.