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

# Web surface

> Page widths, the AppShell frame, URL routes, tab titles, media keys and fonts for apps opened in a browser.

The `web` surface is any browser without a shell. That covers a 360 px phone browser and a 1920 px desktop window alike, so a web page has to work at both ends. These helpers do the common parts in CSS, so the server render and the first frame already have the right layout.

```tsx theme={null}
import { AppShell, Page, useUrlRoute, useDocumentTitle } from '@cskn/ui';
```

## Page

The page container: centered, capped at one of four widths, with a side gutter that grows with the window (16, 24, then 32 px).

```tsx theme={null}
<Page size="narrow"><Feed /></Page>
<Page size="wide"><Grid min={220}>{cards}</Grid></Page>
```

**size** `'narrow' | 'default' | 'wide' | 'full'` (default: 'default')

`narrow` is 680 px (reading, a form, a feed). `default` is 960 px (most pages). `wide` is 1200 px (grids, dashboards). `full` has no cap.

**as** `'div' | 'main' | 'section' | 'article'` (default: 'div')

The element drawn. Use `main` when the page is the landmark itself.

**padded** `boolean` (default: true)

Top and bottom padding: 16 px, or 24 px from 768 px.

**bleed** `boolean`

No side gutter below 768 px, so a photo grid or a feed runs edge to edge on a phone.

`pageWidths` exports the pixel values. The same widths are CSS variables (`--cskn-page-narrow`, `--cskn-page-default`, `--cskn-page-wide`), for a header that must line up with the page below it.

## AppShell

One list of places, drawn three ways:

* a bottom tab bar on a phone
* an icon rail from 768 px
* a sidebar from 1024 px

The switch is CSS only, so nothing re-mounts when the window is resized. The shell also gives the page a skip link and a `<main>` landmark.

```tsx theme={null}
<AppShell
  brand={<b>Photos</b>}
  items={[
    { key: 'feed', label: 'Feed', icon: 'home', href: '/photos/' },
    { key: 'me', label: 'Profile', icon: 'user', href: '/photos/me' },
    { key: 'settings', label: 'Settings', icon: 'settings', tab: false },
  ]}
  value={section}
  onSelect={key => go(routes[key])}
>
  <Page size="wide">…</Page>
</AppShell>
```

**items** `AppShellItem[]` *required*

`{ key, label, icon?, badge?, href?, tab? }`. `badge` is a count, or `true` for a dot. With `href` the item is a real link: Cmd/Ctrl-click and middle-click open it in a new tab, and a plain click calls `onSelect`. `tab: false` keeps the item out of the phone tab bar, which shows the first five.

**value** `string`

The current item's key. It gets `aria-current="page"`.

**onSelect** `(key) =\> void`

Called on a plain click. Navigate here.

**brand** `ReactNode`

Top of the sidebar: the app's name or logo.

**brandCompact** `ReactNode`

What the icon rail shows instead of `brand`, usually the logo alone. Without it the rail has no brand.

**footer** `ReactNode`

Bottom of the sidebar: account, settings.

**header** `ReactNode`

Drawn above the content at every width, such as a title bar or a search field.

**wide** `'md' | 'lg'` (default: 'lg')

The width from which the sidebar replaces the tab bar.

**rail** `boolean` (default: true)

With `wide="lg"`, show the icon rail between 768 and 1024 px.

**skipLabel / navLabel** `string`

Labels for the skip link (default "Skip to content") and the navigation landmark (default "Main"). Translate them.

> [!NOTE]
>
> `AppShell` is for the web surface. Inside the mobile shell use the [stack navigator](https://docs.cskn.dev/ui/stack/overview.md), and inside the desktop shell use [`DesktopWindow`](https://docs.cskn.dev/ui/desktop).

## useUrlRoute

Keeps the page your app shows in the address bar. Back and Forward walk through it, a refresh stays on it, and a copied link opens it. The app's mount path (`/<slug>` on a user page) is handled for you.

```tsx theme={null}
type Route = { tab: 'home' } | { tab: 'explore' } | { photo: string };

const { route, go, back, href } = useUrlRoute<Route>(
  ({ segments: [a, b] }) =>
    a === 'p' && b ? { photo: b } : a === 'explore' ? { tab: 'explore' } : { tab: 'home' },
  (r) => ('photo' in r ? `/p/${r.photo}` : r.tab === 'home' ? '/' : `/${r.tab}`),
  { transition: true },
);

<a href={href({ photo: p.id })} onClick={e => { e.preventDefault(); go({ photo: p.id }); }}>…</a>
<Button onClick={() => back({ tab: 'home' })}>Back</Button>
```

**parse** `(location: UrlLocation) =\> Route` *required*

Turns `{ path, segments, query }` into a route. It must accept any path, including old or mistyped links: fall back to the home route rather than throwing.

**format** `(route: Route) =\> string` *required*

A path (and query) under the app's mount. Don't include the mount itself.

**options.transition** `boolean` (default: false)

Cross-fade between pages with the browser's View Transitions API on a push and on Back/Forward. Replacing the address never animates. It is skipped where the API is missing and under reduced motion.

**route** `Route`

The current route. Every component that calls the hook sees the same one.

**go(next, \{ replace? })** `void`

Show `next` as a new history entry, or in place with `replace`.

**back(fallback)** `void`

The browser's Back when your app pushed the current entry. Otherwise, for a page opened from a link or a refresh, it shows `fallback` in place, so an in-app Back button never leaves your app.

**href(route)** `string`

The full address of a route, for a real `<a href>`.

Push for the user's own steps: opening a post, switching tabs. Use `replace` for choices your app makes, such as selecting the first item, moving on after a delete, or changing a filter.

A route often names data by id, such as `/p/<id>`. Keep a cache of the objects you already have, and fetch the rest when a link opens straight to one.

> [!WARNING]
>
> Use it on the web surface only. The mobile and desktop shells run their own back stack, so keep `useStackNav` there.

## useDocumentTitle

Sets the browser tab's title while the component is mounted, so tabs, history and bookmarks tell your pages apart.

```tsx theme={null}
useDocumentTitle(note?.title || 'Notes', { suffix: 'Notes' }); // "Shopping · Notes"
```

**title** `string | null | undefined` *required*

The page's own name. A falsy value leaves the tab alone, for example while data loads.

**options.suffix** `string`

Added after the title, usually the app's name.

**options.restore** `boolean` (default: true)

Put the previous title back on unmount.

Call it once per page, not in shared components. The deepest mounted page wins.

## useMediaKeys

The keys people expect from a media player in a browser, for as long as the component is mounted.

```tsx theme={null}
useMediaKeys({
  onPlayPause: toggle,
  onSeek: (delta) => seekBy(delta),
  onMute: toggleMute,
  onNext: next,
});
```

| Key | Handler |
| - | - |
| Space, K, the ⏯ key | `onPlayPause` |
| ← / → | `onSeek(∓seekStep)`, default 5 seconds |
| J / L | `onSeek(∓longSeekStep)`, default 10 seconds |
| ↑ / ↓ | `onVolume(±0.1)` |
| M | `onMute` |
| F | `onFullscreen` |
| Shift+N, the ⏭ key | `onNext` |
| Shift+P, the ⏮ key | `onPrevious` |
| 0–9 | `onSeekToFraction(n / 10)` |

A key without a handler is left alone. Nothing fires while the user is typing, while a modifier key is held, or while an open dialog has the focus. Space on a button stays that button's key.

**options** `\{ enabled?, seekStep?, longSeekStep? \}`

`enabled` defaults to `true`.

> [!TIP]
>
> Give `onVolume` only on a page that is the player. It takes the arrow keys away from page scrolling.

## Responsive chrome

`Show` and `Hide` take `mode="css"`. Both branches are mounted, and a media query hides one, so the first frame is already right and resizing re-mounts nothing. Use it for layout chrome, and keep the default `mode="js"` for heavy subtrees. See [Responsive](https://docs.cskn.dev/ui/layout.md#responsive).

```tsx theme={null}
<Show above="lg" mode="css"><DetailPane /></Show>
```

## Hover on hand-styled controls

Kit components have hover states. For a control you style yourself, add the class `cskn-hoverable`. It tints the control on hover with an inset shadow, which works even over an inline `background`.

```tsx theme={null}
<div role="button" tabIndex={0} className="cskn-hoverable" style={{ background: tile }}>…</div>
```

## Fonts and theme color

Load the fonts every page uses in `index.html`, as `<link rel="preconnect">` plus `<link rel="stylesheet">`. Don't use a CSS `@import`: it waits for your own CSS before it even starts.

For a font only one page or surface needs, call `loadFonts`. It adds the preconnects, loads the stylesheet once per document, and adds `display=swap` when the URL has no `display` of its own.

```tsx theme={null}
import { loadFonts } from '@cskn/ui';

loadFonts('https://fonts.googleapis.com/css2?family=Inter:wght@400;600');
```

The root `UIProvider` keeps `<meta name="theme-color">` in step with your theme's background, following light, dark and in-app theme switches. If `index.html` declares its own `theme-color`, the provider leaves it alone.

## Overlays and toasts on wide screens

You don't have to do anything for these:

* A [`Sheet`](https://docs.cskn.dev/ui/components/overlays#sheet) opens as a centered panel in a browser window at least 768 px wide with a mouse, and as a bottom sheet everywhere else.
* [Toasts](https://docs.cskn.dev/ui/components/feedback.md#toast) sit in the bottom-right corner on a browser at least 1024 px wide with a mouse.


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