Skip to main content
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.

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).
'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.
'div' | 'main' | 'section' | 'article'
default:"'div'"
The element drawn. Use main when the page is the landmark itself.
boolean
default:"true"
Top and bottom padding: 16 px, or 24 px from 768 px.
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.
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.
string
The current item’s key. It gets aria-current="page".
(key) => void
Called on a plain click. Navigate here.
ReactNode
Top of the sidebar: the app’s name or logo.
ReactNode
What the icon rail shows instead of brand, usually the logo alone. Without it the rail has no brand.
Bottom of the sidebar: account, settings.
ReactNode
Drawn above the content at every width, such as a title bar or a search field.
'md' | 'lg'
default:"'lg'"
The width from which the sidebar replaces the tab bar.
boolean
default:"true"
With wide="lg", show the icon rail between 768 and 1024 px.
string
Labels for the skip link (default “Skip to content”) and the navigation landmark (default “Main”). Translate them.
AppShell is for the web surface. Inside the mobile shell use the stack navigator, and inside the desktop shell use DesktopWindow.

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.
(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.
(route: Route) => string
required
A path (and query) under the app’s mount. Don’t include the mount itself.
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
The current route. Every component that calls the hook sees the same one.
void
Show next as a new history entry, or in place with replace.
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.
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.
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.
string | null | undefined
required
The page’s own name. A falsy value leaves the tab alone, for example while data loads.
string
Added after the title, usually the app’s name.
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.
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.
{ enabled?, seekStep?, longSeekStep? }
enabled defaults to true.
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.

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.

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.
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 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 sit in the bottom-right corner on a browser at least 1024 px wide with a mouse.