Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Live preview

Start from a complete portal frame, then change one part at a time to fit the product.

A complete portal shell
Three nav groups, badges, a brand, a searchable topbar and a footer.
Skip to content
Dashboard

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

© 2026 Acme. All rights reserved.
Show code
<app-shell>
    <app-shell-brand><app-icon name="box-seam" size="24" class="text-primary" /><span class="app-sidebar-brand-text">Acme</span></app-shell-brand>
    <app-nav-group label="Overview">
        <app-nav-link label="Dashboard" icon="layout-dashboard" href="/" active="true" />
        <app-nav-link label="Reports" icon="file-text" href="/reports" badge="3" badge-tone="Tone.Danger" />
        <app-nav-link label="Docs" icon="book" href="/docs" trailing-icon="external-link" />
    </app-nav-group>
    <app-nav-group label="Workspace">
        <app-nav-link label="Settings" icon="settings">
            <app-nav-link label="General" href="/settings/general" active="true" />
            <app-nav-link label="Billing" href="/settings/billing" />
        </app-nav-link>
    </app-nav-group>
    <app-shell-topbar-start><span class="card-title m-0">Dashboard</span></app-shell-topbar-start>
    <app-shell-topbar-end>
        <app-search placeholder="Search…" size="Sm" />
        <app-action-icon icon="bell" label="Notifications" />
        <app-button variant="Solid" tone="Primary" left-icon="plus">Create</app-button>
        <app-avatar name="Ravi Kumar" />
    </app-shell-topbar-end>
    <app-shell-content>@RenderBody()</app-shell-content>
    <app-shell-footer><div class="p-2 text-center">© 2026 Acme</div></app-shell-footer>
</app-shell>

Current page

Pass the current path and the shell lights the matching item, so the highlight never drifts from the URL.

Matched from the URL
The shell is at /app/leave/42, so Leave is lit and Home is not.
Show code
@* No active anywhere: the request path decides. *@
<app-shell>
    <app-nav-group label="Me">
        <app-nav-link label="Home" icon="home-2" href="/" />
        <app-nav-link label="Leave" icon="calendar" href="/leave" />
        <app-nav-link label="People" icon="people" href="/people" match-also="/directory" />
        <app-nav-link label="Reports" icon="chart" href="/reports" match="exact" />
    </app-nav-group>
</app-shell>
A long menu opens at the current section
The menu is taller than the frame and the page is Tax declarations, so the sidebar opens with Payroll's header at the top.
Show code
@* The page is in the fourth section: the sidebar opens with Payroll's header at the top. *@
<app-shell current-path="/app/payroll/tax">
    <app-nav-group label="Overview">…</app-nav-group>
    <app-nav-group label="People">…</app-nav-group>
    <app-nav-group label="Leave">…</app-nav-group>
    <app-nav-group label="Payroll">
        <app-nav-link label="Payslips" icon="receipt" href="/app/payroll/payslips" />
        <app-nav-link label="Tax declarations" icon="task-square" href="/app/payroll/tax" />
        <app-nav-link label="Reimbursements" icon="check-circle" href="/app/payroll/claims" />
    </app-nav-group>
    <app-nav-group label="Settings">…</app-nav-group>
</app-shell>

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.

Controlled rail state
The page sets collapsed from its own state, so the choice can be kept.
Show code
@* The page sets collapsed; the shell draws the rail from its first paint *@
<app-shell collapsed="true">…</app-shell>

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.

no-sidebar
The sidebar and its toggle are gone; the content spans the full width. Use it for a checkout flow, an onboarding wizard, or a print-style report.
Skip to content

New invoice

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

Step 2 of 4
Show code
<app-shell no-sidebar="true">
    <app-shell-topbar-start><h2 class="card-title m-0">New invoice</h2></app-shell-topbar-start>
    <app-shell-topbar-end><app-button variant="Ghost">Cancel</app-button></app-shell-topbar-end>
    <app-shell-content>...page...</app-shell-content>
    <app-shell-footer><div class="p-2 text-center">Step 2 of 4</div></app-shell-footer>
</app-shell>

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.

Collapse vs drawer
Narrow the window under lg to see the sidebar become a drawer.
Skip to content
Dashboard
Page content
Show code
@* Let the shell own the rail state *@
<app-shell>…</app-shell>
Top navigation
Three destinations in the topbar, and an account menu with a head line, a section of two buttons and a full-width sign-out button.
Skip to content

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

Show code
<app-shell nav="Top">
    <app-shell-brand><span class="app-sidebar-brand-text card-title">Acme</span></app-shell-brand>
    <app-nav-group>
        <app-nav-link label="Dashboard" icon="home-2" href="/app" />
        <app-nav-link label="Clients" icon="building-2" href="/app/clients" />
        <app-nav-link label="Reports" icon="file-text" href="/app/reports" />
    </app-nav-group>
    <app-shell-user-menu name="Priya Sharma" role="Senior Developer" profile-href="/Profile" logout-action="/Logout" logout-variant="Button">
        <app-shell-user-menu-head>Employee 4821</app-shell-user-menu-head>
        <app-shell-user-menu-section>
            <app-button variant="Outline" block="true">Switch workspace</app-button>
            <app-button variant="Outline" block="true">Add a workspace</app-button>
        </app-shell-user-menu-section>
    </app-shell-user-menu>
    <app-shell-topbar-start><h2 class="card-title m-0">Clients</h2></app-shell-topbar-start>
    <app-shell-content>@RenderBody()</app-shell-content>
</app-shell>

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.

All three, live
Open the bell, type in search and open the account menu.
Skip to content

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

Show code
@* _Layout.cshtml: the bell's POST needs the token in the head. *@
<app-csrf-meta />

<app-shell>
    …
    <app-shell-search src="/Search?handler=Suggest" results-href="/Search" placeholder="Search people, pages, documents" />
    <app-shell-notifications src="/Notifications?handler=Panel" unread="@Model.Unread"
        read-action="/Notifications?handler=ReadAll" view-all-href="/Notifications" />
    <app-shell-user-menu name="@User.Identity.Name" role="Senior Developer" roles="Developer, Tester" photo="@photoUrl"
        profile-href="/Profile" logout-action="/Logout">
        <app-shell-user-menu-item label="Change password" icon="lock" href="/Account/Password" />
        <app-shell-user-menu-divider />
    </app-shell-user-menu>
    …
</app-shell>

// The handlers answer fragments (Webority.Ui.Razor.Shell):
public IActionResult OnGetPanel() => this.Notifications(items, unread);   // NotificationItem(Title, Time, Href, Read, Icon, Id)
public IActionResult OnGetSuggest(string q) => this.SearchResults(groups, q, $"/Search?q={Uri.EscapeDataString(q)}");

Phone tab bar

Below 768px the items marked as tabs sit in a bar fixed to the bottom, each at least 44px tall.

Four destinations and More
Four tabs and a More button that opens the navigation drawer.
Skip to content
Approvals

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

Show code
<app-nav-link label="Home" icon="home-2" href="/" tab="true" />
<app-nav-link label="Requests" icon="clipboard-text" href="/requests" badge="2" tab="true" />
<app-nav-link label="Approvals" icon="task-square" href="/approvals" tab="true" />
<app-nav-link label="My profile" icon="profile-circle" href="/profile" tab="true" tab-label="Me" />
<app-nav-link label="Payslips" icon="receipt" href="/payslips" />   @* in the drawer, behind More *@

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 }.

Two folding groups
Click a group heading to fold it, then reload: it stays folded. Ship has sub-headings.
Skip to content

Dashboard

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

Show code
<app-nav-group label="DevOps" key="ship" collapsible="true">
    <app-nav-header>Ship</app-nav-header>
    <app-nav-link label="Releases" icon="send" href="/releases" />
    <app-nav-link label="Builds" icon="folder-kanban" href="/builds" />
    <app-nav-header>Run</app-nav-header>
    <app-nav-link label="Monitoring" icon="activity" href="/monitoring" />
</app-nav-group>
<app-nav-group label="Admin" key="admin" collapsible="true">...</app-nav-group>

Brand top bar and launcher

Brand top bar with a launcher
The bar takes the brand colour, and the Assistant button floats over the page's bottom end corner.
Skip to content

Dashboard

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

Show code
<app-shell topbar-tone="Primary">
    <app-shell-brand><app-icon name="box-seam" size="24" class="text-primary"></app-icon><span class="app-sidebar-brand-text card-title">Acme</span></app-shell-brand>
    <app-nav-group label="Overview">
        <app-nav-link label="Dashboard" icon="layout-dashboard" href="/" active="true" />
        <app-nav-link label="Reports" icon="file-text" href="/reports" />
    </app-nav-group>
    <app-shell-topbar-start><h2 class="card-title m-0">Dashboard</h2></app-shell-topbar-start>
    <app-shell-topbar-end><app-avatar name="Ravi Kumar"></app-avatar></app-shell-topbar-end>
    <app-shell-launcher><app-button left-icon="sparkles">Assistant</app-button></app-shell-launcher>
    <app-shell-content>...page...</app-shell-content>
</app-shell>

Every option

Every value of every prop, one cell each.

groups: nav groups and items

(default) the nav groups
Skip to content
Dashboard
Page content
no groups: the sidebar shows only the brand
Skip to content
Dashboard
Page content
a group with no label: no divider label above its items
Skip to content
Dashboard
Page content
collapsible with a key: the group folds from its heading
Skip to content
Dashboard
Page content

href: a parent link with child items

href on a parent with children: the label links here, the chevron opens the list
Skip to content
Dashboard
Page content

children: the routed page

children: the routed page (React children, Razor app-shell-content)
Skip to content
Dashboard
Page content

brand: the logo row

(default) brand: the logo row at the top of the sidebar
Skip to content
Dashboard
Page content
no brand: the sidebar opens on the nav
Skip to content
Dashboard
Page content

logoLight, logoDark, markLight, markDark (React) / logo-light, logo-dark, mark-light, mark-dark (Razor)

logo-light: the full logo image shown on the open sidebar
Skip to content
Dashboard
Page content
logo-dark: the dark-mode twin of logo-light
Skip to content
Dashboard
Page content
mark-light: the square mark shown on the collapsed rail
mark-dark: the dark-mode twin of mark-light

brandName, brandHref, brandLabel (React) / alt, href, label on app-shell-brand (Razor)

alt on app-shell-brand (React brandName): read aloud for the logo
Skip to content
Dashboard
Page content
href and label on app-shell-brand (React brandHref, brandLabel): the logo row becomes a link
Skip to content
Dashboard
Page content

sidebarStart, sidebarStartCompact (React) / app-shell-sidebar-start, app-shell-sidebar-start-compact (Razor)

(default), neither slot filled
Skip to content
Dashboard
Page content
sidebar-start: between the brand and the nav, hidden once collapsed
Skip to content
Dashboard
Page content
sidebar-start-compact: the same spot on the collapsed rail

sidebarFooter, sidebarFooterItems (React) / app-shell-sidebar-footer (Razor)

sidebar-footer: a node pinned below the nav
Skip to content
Dashboard
Page content
sidebar-footer links: flat links pinned below the menu
Skip to content
Dashboard
Page content

topbarStart, topbarEnd (React) / app-shell-topbar-start, app-shell-topbar-end (Razor)

(default) topbar-start and topbar-end filled
Skip to content
Dashboard
Page content
topbar-start: a long title ellipsises, topbar-end stays pinned
Skip to content
A remarkably long page title that does not fit the bar
Page content

footer (React) / app-shell-footer (Razor)

(default) no footer
Skip to content
Dashboard
Page content
footer: a bar pinned under the content column
Skip to content
Dashboard
Page content
© 2026 Acme

launcher (React) / app-shell-launcher (Razor)

(default) no launcher
Skip to content
Dashboard
Page content
launcher: a floating button over the page's bottom end corner
Skip to content
Dashboard
Page content

collapsed, onCollapsedChange (React) / collapsed (Razor)

(default) expanded
Skip to content
Dashboard
Page content
collapsed="true": the icon rail
React only: onCollapsedChange, Razor keeps the rail with collapsed and remember-collapsed
Skip to content
Dashboard
Page content

noSidebar (React) / no-sidebar (Razor)

(default) with sidebar
Skip to content
Dashboard
Page content
no-sidebar="true": full-width single column
Skip to content
Dashboard
Page content

density

density="comfortable" (default)
Skip to content
Dashboard
Page content
density="compact": 12px content top padding
Skip to content
Dashboard
Page content

itemHeight (React) / item-height (Razor)

(default) item-height unset: the density's row height
Skip to content
Dashboard
Page content
item-height="48": 48px sidebar rows
Skip to content
Dashboard
Page content

iconVariant (React) / icon-variant (Razor)

icon-variant="linear" (default)
Skip to content
Dashboard
Page content
icon-variant="outline"
Skip to content
Dashboard
Page content
icon-variant="bold"
Skip to content
Dashboard
Page content
icon-variant="bulk"
Skip to content
Dashboard
Page content
icon-variant="broken"
Skip to content
Dashboard
Page content
icon-variant="twotone"
Skip to content
Dashboard
Page content

topbarTone (React) / topbar-tone (Razor)

topbar-tone="neutral" (default)
Skip to content
Dashboard
Page content
topbar-tone="primary"
Skip to content
Dashboard
Page content

nav

nav="side" (default)
Skip to content
Dashboard
Page content
nav="top"
Skip to content
Acme
Dashboard
Page content

navLabel, currentPath (React) / nav-label, current-path (Razor)

nav-label="Primary navigation": the nav's accessible name
Skip to content
Dashboard
Page content
current-path="/app/leave/42": lights the matching item
Skip to content
Dashboard
Page content

rememberCollapsed, collapsedCookie, foldedCookie (React) / remember-collapsed, collapsed-cookie, folded-cookie (Razor)

(default) the rail state is not remembered
Skip to content
Dashboard
Page content
remember-collapsed="true": the rail state is kept in a cookie
Skip to content
Dashboard
Page content
collapsed-cookie="my-rail": the cookie that holds the rail state
Skip to content
Dashboard
Page content
folded-cookie="my-folds": the cookie that holds the folded groups
Skip to content
Dashboard
Page content

tabBarLabel, moreLabel (React) / tab-bar-label, more-label (Razor)

tab-bar-label="Main tabs": the phone tab bar's accessible name
more-label="Menu": the label of the More button

skipLabel, openNavLabel, expandNavLabel, collapseNavLabel, newLabel, togglePagesLabel, accountMenuLabel (React) / the same names in kebab case (Razor)

skip-label="Skip to main content"
Skip to main content
Dashboard
Page content
open-nav-label="Open menu"
Skip to content
Dashboard
Page content
expand-nav-label="Expand menu"
Skip to content
Dashboard
Page content
collapse-nav-label="Collapse menu"
Skip to content
Dashboard
Page content
new-label="Fresh": the pill text on a row with new-until
Skip to content
Dashboard
Page content
toggle-pages-label="Show {name} pages": the fold button's name
Skip to content
Dashboard
Page content
account-menu-label="Account for {name}": the account menu's name
Skip to content
Dashboard
Page content

unreadLabel, markAllReadLabel, viewAllLabel, loadingNotificationsText, noUnreadText, unreadNotificationsText, unreadBellLabel (React) / the same names in kebab case (Razor)

unread-label="Unread alerts"
Skip to content
Dashboard
Page content
mark-all-read-label="Clear all"
Skip to content
Dashboard
Page content
view-all-label="See all": the link under the list
Skip to content
Dashboard
Page content
loading-notifications-text="Fetching…": shown while the list loads
Skip to content
Dashboard
Page content
no-unread-text="All caught up": read aloud when nothing is unread
Skip to content
Dashboard
Page content
unread-notifications-text="{count} alerts"
Skip to content
Dashboard
Page content
unread-bell-label="{label}, {count} alerts": the bell's name
Skip to content
Dashboard
Page content

searchResultsLabel, noResultsText, noResultsForText, resultsCountText, resultCountText (React) / the same names in kebab case (Razor)

search-results-label="Matches"
Skip to content
Dashboard
Page content
no-results-text="Nothing matches"
Skip to content
Dashboard
Page content
no-results-for-text="Nothing for “{value}”"
Skip to content
Dashboard
Page content
results-count-text="{count} matches"
Skip to content
Dashboard
Page content
result-count-text="{count} match": the singular
Skip to content
Dashboard
Page content

roleLabel, rolesLabel (React) / role-label, roles-label (Razor)

role-label="Position:"
Skip to content
Dashboard
Page content
roles-label="Teams:"
Skip to content
Dashboard
Page content

userMenu (React) / app-shell-user-menu (Razor)

(default) no account menu
Skip to content
Dashboard
Page content
app-shell-user-menu: the name, role and sign-out
Skip to content
Dashboard
Page content

notifications (React) / app-shell-notifications (Razor)

(default) no bell
Skip to content
Dashboard
Page content
app-shell-notifications: the bell with 3 unread
Skip to content
Dashboard
Page content
app-shell-notifications: the bell with nothing unread
Skip to content
Dashboard
Page content

search (React) / app-shell-search (Razor)

(default) no search
Skip to content
Dashboard
Page content
app-shell-search: the topbar search field
Skip to content
Dashboard
Page content

linkComponent (React only)

React only: linkComponent, Razor links are plain anchors
Skip to content
Dashboard
Page content

className (React) / class (Razor)

class="text-body-secondary": an extra class on the shell root
Skip to content
Dashboard
Page content

Guidance

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.

linear outline bold bulk broken twotone
neutral primary
default brand
side top
Skip to content
Dashboard

Dashboard

Your workspace at a glance. Updated a moment ago.

Open invoices
₹4,82,000
8% vs last month
Active clients
128
4 new
Overdue
6
2 since Friday
Reports due
3
today
Recent approvals
Acme Corp: invoice #2041Approved
Globex retainerPending
Initech renewalRejected
Umbrella Ltd: SOWIn review

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.

React, generated from the controls
<AppShell
  groups={groups}
  onCollapsedChange={fn}
  brand={<><AppIcon name="box-seam" size={24} className="text-primary" /><span className="app-sidebar-brand-text">Acme</span></>}
  topbarStart={<h2>Dashboard</h2>}
  topbarEnd={<><AppButton variant="solid" tone="primary" leftIcon="plus">Create</AppButton><AppAvatar name="Ravi Kumar" /></>}
  currentPath="/app/dashboard"
>
  <Outlet />
</AppShell>
Razor, the same props
<app-shell current-path="/app/dashboard">
    <app-shell-brand><app-icon name="box-seam" size="24" class="text-primary"></app-icon><span class="app-sidebar-brand-text">Acme</span></app-shell-brand>
    <app-nav-group label="Overview">…</app-nav-group>
    <app-shell-topbar-start><span class="card-title m-0">Dashboard</span></app-shell-topbar-start>
    <app-shell-topbar-end><app-button variant="Solid" tone="Primary" left-icon="plus">Create</app-button><app-avatar name="Ravi Kumar" /></app-shell-topbar-end>
    <app-shell-content>@RenderBody()</app-shell-content>
</app-shell>

31 props.

Less common 31 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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.