App Shell

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import AppShell, AppShellFit, AppShellRouteFocus from @prepared911/ui/blocks/app-shell. See props.ts for the props and schema.ts for the declaration (inputs and slots).

Props

Prop	Type	Notes
`navbar`	`ReactElement`	Required. A Navbar. Fixed.
`main`	`ReactNode`	Required. The page. Scrolls inside `main`.
`skipLinkLabel`	`LocalizedMessage`	Required. Names the skip link.
`sidebar`	`ReactElement`	A Sidebar at the inline-start edge. Fixed.
`banner`	`ReactElement`	One Banner under the bar, across the full width.
`dock`	`ReactNode`	Space reserved under `main` for the Dock.
`fit`	`AppShellFit`	`Viewport` (default, `100dvh`) or `Container` (the parent's block size).
`routeKey`	`string`	Identity of the current page.
`routeFocus`	`AppShellRouteFocus`	`None` (default) or `Main`: where focus goes when `routeKey` changes.
`routeAnnouncement`	`LocalizedMessage`	Name of the page, announced politely when it changes.
`mainRef`	`Ref<HTMLElement>`	The `main` element, which is the scroll container.
`mainId`	`string`	Id of `main` and the skip link's target. Generated when omitted.
`mainData`	`AppShellMainData`	`data-*` attributes for `main`, such as the router's scroll restoration id.
`className`, `ref`, `id`		On the shell's root `div`.
`data-*`	`string`	On the shell's root `div`, such as `data-test-id`. A reserved state name is dropped, as Box does. `main` takes its own through `mainData`.

DOM

The main element is a raw element: Box renders main but removes tabIndex, and the skip link needs a target that script can focus. It takes a class, mainId, mainData and mainRef and nothing else.

Props (generated)

Name	Type	Default	Description
`main`	`ReactNode`	—	The page. It renders inside `main`, which scrolls on its own. In a TanStack Router app this is `<Outlet />`.
`navbar`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	The application bar: a `Navbar` element. Its `header` is the page's banner landmark, so the shell places it outside `main` and outside any sectioning element. The bar stays fixed whatever `main` does.
`skipLinkLabel`	`LocalizedMessage`	—	Name of the skip link, the first control in the tab order, which moves focus to `main`.
`banner`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	One `Banner` element directly under the bar, across the full width of the shell, above the sidebar as well. The slot takes a single element, so notices never stack.
`className`	`string`	—	@deprecated Pass layout through enum props and shipped parts. Request a missing case via find-pattern.
`dock`	`ReactNode`	—	Space the shell reserves for the Dock (CORE-1041), centered under `main` and never over it. Omit it and no space is reserved.
`fit`	`AppShellFit`	`AppShellFit.Viewport`	What the shell's block size follows.
`id`	`string`	—	Id of the shell's root element.
`mainData`	`AppShellMainData`	—	`data-*` attributes for `main`. TanStack Router's element scroll restoration finds the container by `data-scroll-restoration-id`.
`mainId`	`string`	—	Id of the `main` element, which is also the skip link's target. A generated id is used when omitted.
`mainRef`	`Ref<HTMLElement>`	—	Ref to the `main` element, which is the shell's scroll container.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the shell's root element.
`routeAnnouncement`	`LocalizedMessage`	—	The name of the page the shell just showed. It is announced politely when it changes, so a screen reader hears the route change even though focus did not move. Pass the page title.
`routeFocus`	`AppShellRouteFocus`	`AppShellRouteFocus.None`	Where focus goes when `routeKey` changes.
`routeKey`	`string`	—	Identity of the current page, usually the pathname. When it changes after the first render the shell applies `routeFocus`. Leave it out for a shell that never changes page.
`sidebar`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	The primary navigation: a `Sidebar` element. It sits at the inline-start edge, below the bar and the banner, and stays fixed; it scrolls its own content. Omit it and `main` takes the width.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

App Shell / Usage

App Shell / Accessibility

On this page

App Shell

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import AppShell, AppShellFit, AppShellRouteFocus from @prepared911/ui/blocks/app-shell. See props.ts for the props and schema.ts for the declaration (inputs and slots).

Props

Prop	Type	Notes
`navbar`	`ReactElement`	Required. A Navbar. Fixed.
`main`	`ReactNode`	Required. The page. Scrolls inside `main`.
`skipLinkLabel`	`LocalizedMessage`	Required. Names the skip link.
`sidebar`	`ReactElement`	A Sidebar at the inline-start edge. Fixed.
`banner`	`ReactElement`	One Banner under the bar, across the full width.
`dock`	`ReactNode`	Space reserved under `main` for the Dock.
`fit`	`AppShellFit`	`Viewport` (default, `100dvh`) or `Container` (the parent's block size).
`routeKey`	`string`	Identity of the current page.
`routeFocus`	`AppShellRouteFocus`	`None` (default) or `Main`: where focus goes when `routeKey` changes.
`routeAnnouncement`	`LocalizedMessage`	Name of the page, announced politely when it changes.
`mainRef`	`Ref<HTMLElement>`	The `main` element, which is the scroll container.
`mainId`	`string`	Id of `main` and the skip link's target. Generated when omitted.
`mainData`	`AppShellMainData`	`data-*` attributes for `main`, such as the router's scroll restoration id.
`className`, `ref`, `id`		On the shell's root `div`.
`data-*`	`string`	On the shell's root `div`, such as `data-test-id`. A reserved state name is dropped, as Box does. `main` takes its own through `mainData`.

DOM

Props (generated)

Name	Type	Default	Description
`main`	`ReactNode`	—	The page. It renders inside `main`, which scrolls on its own. In a TanStack Router app this is `<Outlet />`.
`navbar`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	The application bar: a `Navbar` element. Its `header` is the page's banner landmark, so the shell places it outside `main` and outside any sectioning element. The bar stays fixed whatever `main` does.
`skipLinkLabel`	`LocalizedMessage`	—	Name of the skip link, the first control in the tab order, which moves focus to `main`.
`banner`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	One `Banner` element directly under the bar, across the full width of the shell, above the sidebar as well. The slot takes a single element, so notices never stack.
`className`	`string`	—	@deprecated Pass layout through enum props and shipped parts. Request a missing case via find-pattern.
`dock`	`ReactNode`	—	Space the shell reserves for the Dock (CORE-1041), centered under `main` and never over it. Omit it and no space is reserved.
`fit`	`AppShellFit`	`AppShellFit.Viewport`	What the shell's block size follows.
`id`	`string`	—	Id of the shell's root element.
`mainData`	`AppShellMainData`	—	`data-*` attributes for `main`. TanStack Router's element scroll restoration finds the container by `data-scroll-restoration-id`.
`mainId`	`string`	—	Id of the `main` element, which is also the skip link's target. A generated id is used when omitted.
`mainRef`	`Ref<HTMLElement>`	—	Ref to the `main` element, which is the shell's scroll container.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the shell's root element.
`routeAnnouncement`	`LocalizedMessage`	—	The name of the page the shell just showed. It is announced politely when it changes, so a screen reader hears the route change even though focus did not move. Pass the page title.
`routeFocus`	`AppShellRouteFocus`	`AppShellRouteFocus.None`	Where focus goes when `routeKey` changes.
`routeKey`	`string`	—	Identity of the current page, usually the pathname. When it changes after the first render the shell applies `routeFocus`. Leave it out for a shell that never changes page.
`sidebar`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	The primary navigation: a `Sidebar` element. It sits at the inline-start edge, below the bar and the banner, and stays fixed; it scrolls its own content. Omit it and `main` takes the width.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

App Shell / Usage

App Shell / Accessibility

On this page