On this page
@addTagHelper *, Webority.Ui.RazorLive preview
Start from a complete portal frame, then change one part at a time to fit the product.
Dashboard
Your workspace at a glance. Updated a moment ago.
Scroll this panel. The sidebar and topbar stay put while the page moves beneath them, which is precisely how the shell behaves against the browser window in a real portal. The topbar carries its divider, the account menu on the right never slides off, and a long nav scrolls independently inside the sidebar.
Below lg (narrow your browser under 992px) the sidebar leaves the layout and becomes an off-canvas drawer: open it from the topbar hamburger, dim the page behind a scrim, and close it with the scrim or the Escape key. Nothing about the content column changes. It simply takes the full width. Below md (768px) the links flagged tab also sit in a bar along the bottom of the screen.
Everything here (the nav, the brand, the topbar slots, the footer) is markup you pass as child slots. The shell owns only the structure: the collapse breakpoint, the 72px topbar, the 88px icon rail, the drawer and its focus handling. That is the whole point of not forking it per product.
With nav="top" the brand sits in the topbar. Size it with --wui-shell-top-brand-height (32px) and --wui-shell-top-brand-height-phone (28px, below md), set on any ancestor of the shell. Your own brand markup reads --wui-shell-top-brand-size; a logo or mark image in the slot follows it with no extra CSS.
Current page
Pass the current path and the shell lights the matching item, so the highlight never drifts from the URL.
Collapse to a rail
On wide screens the sidebar can fold into an icon rail, controlled by the product so the choice can be kept.
Dashboard
Your workspace at a glance. Updated a moment ago.
Scroll this panel. The sidebar and topbar stay put while the page moves beneath them, which is precisely how the shell behaves against the browser window in a real portal. The topbar carries its divider, the account menu on the right never slides off, and a long nav scrolls independently inside the sidebar.
Below lg (narrow your browser under 992px) the sidebar leaves the layout and becomes an off-canvas drawer: open it from the topbar hamburger, dim the page behind a scrim, and close it with the scrim or the Escape key. Nothing about the content column changes. It simply takes the full width. Below md (768px) the links flagged tab also sit in a bar along the bottom of the screen.
Everything here (the nav, the brand, the topbar slots, the footer) is markup you pass as child slots. The shell owns only the structure: the collapse breakpoint, the 72px topbar, the 88px icon rail, the drawer and its focus handling. That is the whole point of not forking it per product.
With nav="top" the brand sits in the topbar. Size it with --wui-shell-top-brand-height (32px) and --wui-shell-top-brand-height-phone (28px, below md), set on any ancestor of the shell. Your own brand markup reads --wui-shell-top-brand-size; a logo or mark image in the slot follows it with no extra CSS.
Focused mode: no sidebar
A full-bleed report or a step-by-step wizard reads better without the nav competing. noSidebar drops the side column to a single full-width column, keeping the topbar and footer so the user is never lost.
Rail above lg, drawer below
The rail shows from the large breakpoint up, and below it the sidebar opens as a drawer from the topbar.
Dashboard
Your workspace at a glance. Updated a moment ago.
Scroll this panel. The sidebar and topbar stay put while the page moves beneath them, which is precisely how the shell behaves against the browser window in a real portal. The topbar carries its divider, the account menu on the right never slides off, and a long nav scrolls independently inside the sidebar.
Below lg (narrow your browser under 992px) the sidebar leaves the layout and becomes an off-canvas drawer: open it from the topbar hamburger, dim the page behind a scrim, and close it with the scrim or the Escape key. Nothing about the content column changes. It simply takes the full width. Below md (768px) the links flagged tab also sit in a bar along the bottom of the screen.
Everything here (the nav, the brand, the topbar slots, the footer) is markup you pass as child slots. The shell owns only the structure: the collapse breakpoint, the 72px topbar, the 88px icon rail, the drawer and its focus handling. That is the whole point of not forking it per product.
With nav="top" the brand sits in the topbar. Size it with --wui-shell-top-brand-height (32px) and --wui-shell-top-brand-height-phone (28px, below md), set on any ancestor of the shell. Your own brand markup reads --wui-shell-top-brand-size; a logo or mark image in the slot follows it with no extra CSS.
Account menu, bell and search
The topbar takes search, notifications and the account menu as data in and events out, so the app supplies the content.
Dashboard
Your workspace at a glance. Updated a moment ago.
Scroll this panel. The sidebar and topbar stay put while the page moves beneath them, which is precisely how the shell behaves against the browser window in a real portal. The topbar carries its divider, the account menu on the right never slides off, and a long nav scrolls independently inside the sidebar.
Below lg (narrow your browser under 992px) the sidebar leaves the layout and becomes an off-canvas drawer: open it from the topbar hamburger, dim the page behind a scrim, and close it with the scrim or the Escape key. Nothing about the content column changes. It simply takes the full width. Below md (768px) the links flagged tab also sit in a bar along the bottom of the screen.
Everything here (the nav, the brand, the topbar slots, the footer) is markup you pass as child slots. The shell owns only the structure: the collapse breakpoint, the 72px topbar, the 88px icon rail, the drawer and its focus handling. That is the whole point of not forking it per product.
With nav="top" the brand sits in the topbar. Size it with --wui-shell-top-brand-height (32px) and --wui-shell-top-brand-height-phone (28px, below md), set on any ancestor of the shell. Your own brand markup reads --wui-shell-top-brand-size; a logo or mark image in the slot follows it with no extra CSS.
Phone tab bar
Below 768px the items marked as tabs sit in a bar fixed to the bottom, each at least 44px tall.
Dashboard
Your workspace at a glance. Updated a moment ago.
Scroll this panel. The sidebar and topbar stay put while the page moves beneath them, which is precisely how the shell behaves against the browser window in a real portal. The topbar carries its divider, the account menu on the right never slides off, and a long nav scrolls independently inside the sidebar.
Below lg (narrow your browser under 992px) the sidebar leaves the layout and becomes an off-canvas drawer: open it from the topbar hamburger, dim the page behind a scrim, and close it with the scrim or the Escape key. Nothing about the content column changes. It simply takes the full width. Below md (768px) the links flagged tab also sit in a bar along the bottom of the screen.
Everything here (the nav, the brand, the topbar slots, the footer) is markup you pass as child slots. The shell owns only the structure: the collapse breakpoint, the 72px topbar, the 88px icon rail, the drawer and its focus handling. That is the whole point of not forking it per product.
With nav="top" the brand sits in the topbar. Size it with --wui-shell-top-brand-height (32px) and --wui-shell-top-brand-height-phone (28px, below md), set on any ancestor of the shell. Your own brand markup reads --wui-shell-top-brand-size; a logo or mark image in the slot follows it with no extra CSS.
Foldable groups
A group with collapsible and a key folds from its heading. The folded keys are remembered in the wui-nav-folded cookie (one year, site-wide), and a section holding the current page always opens. A sub-heading inside a group is an item of the form { key, header }.
Dashboard
Your workspace at a glance. Updated a moment ago.
Scroll this panel. The sidebar and topbar stay put while the page moves beneath them, which is precisely how the shell behaves against the browser window in a real portal. The topbar carries its divider, the account menu on the right never slides off, and a long nav scrolls independently inside the sidebar.
Below lg (narrow your browser under 992px) the sidebar leaves the layout and becomes an off-canvas drawer: open it from the topbar hamburger, dim the page behind a scrim, and close it with the scrim or the Escape key. Nothing about the content column changes. It simply takes the full width. Below md (768px) the links flagged tab also sit in a bar along the bottom of the screen.
Everything here (the nav, the brand, the topbar slots, the footer) is markup you pass as child slots. The shell owns only the structure: the collapse breakpoint, the 72px topbar, the 88px icon rail, the drawer and its focus handling. That is the whole point of not forking it per product.
With nav="top" the brand sits in the topbar. Size it with --wui-shell-top-brand-height (32px) and --wui-shell-top-brand-height-phone (28px, below md), set on any ancestor of the shell. Your own brand markup reads --wui-shell-top-brand-size; a logo or mark image in the slot follows it with no extra CSS.
Brand top bar and launcher
Dashboard
Your workspace at a glance. Updated a moment ago.
Scroll this panel. The sidebar and topbar stay put while the page moves beneath them, which is precisely how the shell behaves against the browser window in a real portal. The topbar carries its divider, the account menu on the right never slides off, and a long nav scrolls independently inside the sidebar.
Below lg (narrow your browser under 992px) the sidebar leaves the layout and becomes an off-canvas drawer: open it from the topbar hamburger, dim the page behind a scrim, and close it with the scrim or the Escape key. Nothing about the content column changes. It simply takes the full width. Below md (768px) the links flagged tab also sit in a bar along the bottom of the screen.
Everything here (the nav, the brand, the topbar slots, the footer) is markup you pass as child slots. The shell owns only the structure: the collapse breakpoint, the 72px topbar, the 88px icon rail, the drawer and its focus handling. That is the whole point of not forking it per product.
With nav="top" the brand sits in the topbar. Size it with --wui-shell-top-brand-height (32px) and --wui-shell-top-brand-height-phone (28px, below md), set on any ancestor of the shell. Your own brand markup reads --wui-shell-top-brand-size; a logo or mark image in the slot follows it with no extra CSS.
Every option
Every value of every prop, one cell each.
groups: nav groups and items
(default) the nav groupsno groups: the sidebar shows only the branda group with no label: no divider label above its itemscollapsible with a key: the group folds from its headinghref: a parent link with child items
href on a parent with children: the label links here, the chevron opens the listchildren: the routed page
children: the routed page (React children, Razor app-shell-content)brand: the logo row
(default) brand: the logo row at the top of the sidebarno brand: the sidebar opens on the navlogoLight, logoDark, markLight, markDark (React) / logo-light, logo-dark, mark-light, mark-dark (Razor)
logo-light: the full logo image shown on the open sidebarlogo-dark: the dark-mode twin of logo-lightmark-light: the square mark shown on the collapsed railmark-dark: the dark-mode twin of mark-lightbrandName, brandHref, brandLabel (React) / alt, href, label on app-shell-brand (Razor)
alt on app-shell-brand (React brandName): read aloud for the logohref and label on app-shell-brand (React brandHref, brandLabel): the logo row becomes a linksidebarStart, sidebarStartCompact (React) / app-shell-sidebar-start, app-shell-sidebar-start-compact (Razor)
(default), neither slot filledsidebar-start: between the brand and the nav, hidden once collapsedsidebar-start-compact: the same spot on the collapsed railsidebarFooter, sidebarFooterItems (React) / app-shell-sidebar-footer (Razor)
sidebar-footer: a node pinned below the navsidebar-footer links: flat links pinned below the menutopbarStart, topbarEnd (React) / app-shell-topbar-start, app-shell-topbar-end (Razor)
(default) topbar-start and topbar-end filledtopbar-start: a long title ellipsises, topbar-end stays pinnedfooter (React) / app-shell-footer (Razor)
(default) no footerfooter: a bar pinned under the content columnlauncher (React) / app-shell-launcher (Razor)
(default) no launcherlauncher: a floating button over the page's bottom end cornercollapsed, onCollapsedChange (React) / collapsed (Razor)
(default) expandedcollapsed="true": the icon railReact only: onCollapsedChange, Razor keeps the rail with collapsed and remember-collapsednoSidebar (React) / no-sidebar (Razor)
(default) with sidebarno-sidebar="true": full-width single columndensity
density="comfortable" (default)density="compact": 12px content top paddingitemHeight (React) / item-height (Razor)
(default) item-height unset: the density's row heightitem-height="48": 48px sidebar rowsiconVariant (React) / icon-variant (Razor)
icon-variant="linear" (default)icon-variant="outline"icon-variant="bold"icon-variant="bulk"icon-variant="broken"icon-variant="twotone"topbarTone (React) / topbar-tone (Razor)
topbar-tone="neutral" (default)topbar-tone="primary"nav
nav="side" (default)nav="top"navLabel, currentPath (React) / nav-label, current-path (Razor)
nav-label="Primary navigation": the nav's accessible namecurrent-path="/app/leave/42": lights the matching itemrememberCollapsed, collapsedCookie, foldedCookie (React) / remember-collapsed, collapsed-cookie, folded-cookie (Razor)
(default) the rail state is not rememberedremember-collapsed="true": the rail state is kept in a cookiecollapsed-cookie="my-rail": the cookie that holds the rail statefolded-cookie="my-folds": the cookie that holds the folded groupstabBarLabel, moreLabel (React) / tab-bar-label, more-label (Razor)
tab-bar-label="Main tabs": the phone tab bar's accessible namemore-label="Menu": the label of the More buttonskipLabel, openNavLabel, expandNavLabel, collapseNavLabel, newLabel, togglePagesLabel, accountMenuLabel (React) / the same names in kebab case (Razor)
skip-label="Skip to main content"open-nav-label="Open menu"expand-nav-label="Expand menu"collapse-nav-label="Collapse menu"new-label="Fresh": the pill text on a row with new-untiltoggle-pages-label="Show {name} pages": the fold button's nameaccount-menu-label="Account for {name}": the account menu's nameunreadLabel, markAllReadLabel, viewAllLabel, loadingNotificationsText, noUnreadText, unreadNotificationsText, unreadBellLabel (React) / the same names in kebab case (Razor)
unread-label="Unread alerts"mark-all-read-label="Clear all"view-all-label="See all": the link under the listloading-notifications-text="Fetching…": shown while the list loadsno-unread-text="All caught up": read aloud when nothing is unreadunread-notifications-text="{count} alerts"unread-bell-label="{label}, {count} alerts": the bell's namesearchResultsLabel, noResultsText, noResultsForText, resultsCountText, resultCountText (React) / the same names in kebab case (Razor)
search-results-label="Matches"no-results-text="Nothing matches"no-results-for-text="Nothing for “{value}”"results-count-text="{count} matches"result-count-text="{count} match": the singularroleLabel, rolesLabel (React) / role-label, roles-label (Razor)
role-label="Position:"roles-label="Teams:"userMenu (React) / app-shell-user-menu (Razor)
(default) no account menuapp-shell-user-menu: the name, role and sign-outnotifications (React) / app-shell-notifications (Razor)
(default) no bellapp-shell-notifications: the bell with 3 unreadapp-shell-notifications: the bell with nothing unreadsearch (React) / app-shell-search (Razor)
(default) no searchapp-shell-search: the topbar search fieldlinkComponent (React only)
React only: linkComponent, Razor links are plain anchorsclassName (React) / class (Razor)
class="text-body-secondary": an extra class on the shell rootGuidance
What to do, and what to avoid.
Use it when
- Every authenticated screen in a portal: mount it once, above the outlet.
- The product has more than a handful of destinations.
- You want the same collapse, drawer and topbar behaviour as every sibling product.
Reach for something else when
- It is a public marketing page. → the Razor site layout
- It is a sign-in or sign-up screen, so there is no nav to show. → a plain centred layout
- You need a temporary side panel, not the app's navigation. → AppDrawer
- The session has not resolved yet. → AppSplash
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
31 props.
Less common 31 props
| Prop | Type | Default | Description |
|---|---|---|---|
| collapseddefault false | bool | false | Controlled rail state. Omit it to let the shell own the state. |
| no-sidebardefault false | bool | false | Full-width layout with no side nav, for a focused wizard. There is no tab bar either. |
| navdefault side | Side | Top | side | Where the primary navigation sits: a sidebar, or from lg up the top bar. |
| densitydefault comfortable | Comfortable | Compact | comfortable | Compact sets the content's top padding to 12px. |
| item-heightdefault the density's row height | int | the density's row height | The height of every sidebar row in px, in place of the density's row height. Unset, the rows keep the density's height. A value above zero applies on every pointer, touch included. |
| icon-variantdefault twotone | Linear | Outline | Bold | Bulk | Broken | Twotone | twotone | The iconsax style of every sidebar icon. A row's own iconVariant overrides it; bulk is the filled look. Unset, icons draw in the twotone style. |
| topbar-tonedefault neutral | Neutral | Primary | neutral | The top bar's colour. Primary paints the bar in the primary colour, with the ink that reads on it. The search field keeps its own surface. |
| app-shell-launcherdefault - | markup | - | A floating button pinned to the bottom end corner over the page, such as an assistant launcher. Rendered after the page column. |
| logo-lightdefault - | string | - | Image URL of the full logo shown on the open sidebar. Ship it pre-trimmed; the library fixes only its height. |
| logo-darkdefault - | string | - | Dark-mode twin of logoLight, swapped in under data-theme dark. Needs logoLight. |
| mark-lightdefault - | string | - | Image URL of the square mark shown on the collapsed rail. Without one, the logo is clipped to a square. |
| mark-darkdefault - | string | - | Dark-mode twin of markLight. |
| altdefault - | string | - | The brand name, read by screen readers from the logo, or from the mark when there is no logo. |
| hrefdefault - | string | - | Makes the logo row a link to this address. The link wraps the logo, mark and content, so the content must hold no link of its own. Needs label or alt. |
| labeldefault alt | string | alt | The brand link's accessible name, such as Acme home. Used only with href; defaults to alt. |
| nav-labeldefault Main navigation | string | Main navigation | Accessible name of the sidebar navigation. |
| current-pathdefault the request path | string | the request path | The current location. Rows without active are matched against it. |
| speculationdefault off | "moderate" | off | Write a speculationrules block so the browser prefetches and prerenders same-site links on hover. Sign-out links, [download] links and anything marked data-no-prefetch are excluded. |
| remember-collapseddefault false | bool | false | Remembers the uncontrolled rail state in a cookie. |
| collapsed-cookiedefault wui-shell-collapsed | string | wui-shell-collapsed | The cookie rememberCollapsed uses. |
| folded-cookiedefault wui-nav-folded | string | wui-nav-folded | The cookie that remembers the folded collapsible groups, as their keys joined by dots. |
| tab-bar-labeldefault Quick navigation | string | Quick navigation | Accessible name of the phone tab bar. |
| more-labeldefault More | string | More | Label of the tab bar button that opens the drawer. |
| skip-labeldefault Skip to content | string | Skip to content | Replaces the built-in English text, for other languages. |
| open-nav-labeldefault Open navigation | string | Open navigation | Replaces the built-in English text, for other languages. |
| expand-nav-labeldefault Expand navigation | string | Expand navigation | Replaces the built-in English text, for other languages. |
| collapse-nav-labeldefault Collapse navigation | string | Collapse navigation | Replaces the built-in English text, for other languages. |
| toggle-pages-labeldefault Show or hide {name} pages | string | Show or hide {name} pages | Replaces the built-in English text, for other languages. {name} is the nav item's label. |
| new-labeldefault New | string | New | Replaces the built-in English text, for other languages. |
| classdefault - | string | - | Extra classes on the shell. It merges with the component's own classes. |
| tonedefault default | Default | Brand | default | brand paints the sidebar and its parts with the --color-shell-* tokens. |
<app-nav-group> takes label and may hold one <app-nav-group-after>, markup rendered right after the group's links (hidden on the collapsed rail, shown in the drawer, dropped with a group that has no links). <app-nav-link> takes label, icon, href, badge, badge-tone, trailing-icon and the attributes below, and may nest <app-nav-link> children to become an expandable parent. A link placed directly inside <app-shell-sidebar-footer> is pinned below the scrolling menu, matched and marked active with the menu links (React sidebarFooterItems); it cannot hold child links or tab, and any other markup in the slot follows the links. The slot elements are app-shell-brand, app-shell-sidebar-start, app-shell-sidebar-start-compact, app-shell-sidebar-footer, app-shell-topbar-start, app-shell-topbar-end, app-shell-content, app-shell-footer, and the three topbar parts below.
app-nav-link
8 props.
Less common 8 props
| Prop | Type | Default | Description |
|---|---|---|---|
| hrefdefault - | string | - | With child items, the label link goes here and the chevron alone opens the sub-list. |
| activedefault unset | bool? | unset | Unset: decided from the current path. true forces it (and turns the automatic match off for the shell); false keeps the link out of it. |
| matchdefault prefix | prefix | exact | prefix | exact matches only the same path, not the pages under it. |
| match-alsodefault - | string | - | Comma list of extra path prefixes that also make this link the current page. |
| tabdefault false | bool | false | Also show the link in the phone tab bar (4 plus More, or 5 when every link is a tab; more throws). |
| tab-labeldefault label | string | label | A shorter label for the tab bar. |
| badge-titledefault - | string | - | The badge's hover text, e.g. 3 invoices overdue. |
| new-untildefault - | string | - | An ISO date, yyyy-MM-dd in India time. A green New pill shows after the label through that day, and none after it. |
app-shell-user-menu
9 props.
Less common 9 props
| Prop | Type | Default | Description |
|---|---|---|---|
| namedefault required | string | required | The person's full name; the avatar's initials come from it. |
| roledefault - | string | - | A second line under the name. |
| rolesdefault - | string | - | Portal role names, comma-separated, under the job title as Role: or Roles:. |
| no-trigger-roledefault false | bool | false | Leaves the job title off the topbar trigger, so it shows the name only. The opened menu still shows it. |
| outlineddefault false | bool | false | Draws an always-on outline around the topbar trigger. |
| photodefault - | string | - | Profile photo URL; initials without it. |
| profile-href / profile-labeldefault My profile | string | My profile | The profile link at the top of the menu. |
| logout-action / logout-labeldefault Sign out | string | Sign out | Where the sign-out form POSTs, with the antiforgery token. Never a link. |
| account-menu-labeldefault Account menu for {name} | string | Account menu for {name} | Replaces the built-in English text, for other languages. {name} is the signed-in person's name. |
Rows: <app-shell-user-menu-item label icon href /> (a button without href; other attributes land on it) and <app-shell-user-menu-divider />.
app-shell-notifications
13 props.
Less common 13 props
| Prop | Type | Default | Description |
|---|---|---|---|
| srcdefault required | string | required | The fragment the list loads from when the panel opens (ShellFragments.Notifications). |
| unreaddefault 0 | int | 0 | The count for the first paint; 99+ above 99. |
| unread-labeldefault Unread | string | Unread | Replaces the built-in English text, for other languages. |
| loading-notifications-textdefault Loading… | string | Loading… | Replaces the built-in English text, for other languages. |
| no-unread-textdefault No unread notifications | string | No unread notifications | Replaces the built-in English text, for other languages. Read aloud when the unread count drops to zero. |
| unread-notifications-textdefault {count} unread notifications | string | {count} unread notifications | Replaces the built-in English text, for other languages. {count} is the unread count. |
| unread-bell-labeldefault {label}, {count} unread | string | {label}, {count} unread | Replaces the built-in English text, for other languages. {label} is the bell's label and {count} the unread count. |
| read-actiondefault - | string | - | Where "Mark all read" POSTs (needs <app-csrf-meta />). |
| mark-all-read-labeldefault Mark all read | string | Mark all read | Replaces the built-in English text, for other languages. |
| poll-secondsdefault 60 | int | 60 | How often the count refreshes while the tab is visible; 0 turns it off. |
| view-all-hrefdefault - | string | - | A "View all" link under the list. |
| view-all-labeldefault View all | string | View all | Replaces the built-in English text, for other languages. |
| label / empty-textdefault Notifications | string | Notifications | The bell's name and heading; the text for an empty list. |
app-shell-search
10 props.
Less common 10 props
| Prop | Type | Default | Description |
|---|---|---|---|
| srcdefault required | string | required | The fragment suggestions load from (ShellFragments.SearchResults). |
| results-hrefdefault - | string | - | The full results page Enter opens when no suggestion is chosen. |
| paramdefault q | string | q | The query-string name of the typed text. |
| min-chars / debounce-msdefault 2 / 250 | int | 2 / 250 | Fewest characters, and quiet time after the last keystroke, before suggestions load. |
| placeholderdefault Search | string | Search | Placeholder and accessible name. |
| search-results-labeldefault Search results | string | Search results | Replaces the built-in English text, for other languages. |
| no-results-textdefault No results | string | No results | Replaces the built-in English text, for other languages. |
| no-results-for-textdefault No results for “{value}” | string | No results for “{value}” | Replaces the built-in English text, for other languages. {value} is the search text. |
| results-count-textdefault {count} results | string | {count} results | Replaces the built-in English text, for other languages. {count} is the number of results. |
| result-count-textdefault {count} result | string | {count} result | Replaces the built-in English text, for other languages. {count} is the number of results (one). |
Screen reader
3 notes- The sidebar is a nav landmark named by navLabel, the phone tab bar is a nav named by tabBarLabel, a skip link jumps to the content, and the current page carries aria-current.
- The collapse, menu and sub-list buttons are named and report aria-expanded; Escape closes the open navigation drawer, and a closed sub-list is inert and hidden from assistive technology.
- The account menu button is named with the person's name, the bell is named with its unread count and announces changes in a polite live region, and the topbar search is a combobox with a listbox of suggestions.