Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Navblock

Navblock

The Navblock is the vertical, sidebar-style navigation companion to "aegov-navbar". It composes one or more "aegov-navblock-item" children that can each be a plain link, a link with a leading icon, or a parent group containing nested sub-items that expand and collapse like an accordion — the pattern most application sidebars use to organise sections by topic.

Navigation
Status
Active
Introduced
4.0.x
View source code

Anatomy

aegov-navblock renders a <nav> landmark with an optional <h2> title, wrapping a <div role="list"> of aegov-navblock-item children. Each item host carries role="listitem" and contains a row — a real <a> (leaf with a destination), a toggle <button> (parent with sub-items), or a plain <button>/non-interactive <span> otherwise — plus, for a parent row, a collapsible <div> wrapper holding its own nested <div role="list"> of sub-items.

Image showing anatomy of a navblock

Item Name Description
1 Nav landmark The <nav> element, labelled via label-nav
2 Block title Optional heading from block-title or the title slot
3 Item row The <a>/<button>/<span> rendered by each item
4 Leading icon Optional icon via the icon-start slot
5 Expand/collapse indicator Chevron or plus icon, shown only on parent rows
6 Sub-region The nested <div role="list"> of an open parent's subnav children

Navblock basics

A navblock is one or more aegov-navblock-item children. An item with href and no children renders as a link; an item with nested aegov-navblock-item children automatically becomes a collapsible group — authors do not need to add slot="subnav" themselves, nested items are promoted into it automatically.

Dashboard Reports Sales Users Settings
<aegov-navblock block-title="Workspace" label-nav="Project sidebar">
  <aegov-navblock-item href="/" is-active="true">Dashboard</aegov-navblock-item>
  <aegov-navblock-item>
    Reports
    <aegov-navblock-item href="/r/sales">Sales</aegov-navblock-item>
    <aegov-navblock-item href="/r/users">Users</aegov-navblock-item>
  </aegov-navblock-item>
  <aegov-navblock-item href="/settings">Settings</aegov-navblock-item>
</aegov-navblock>

Collapsible and flat variants

variant switches the visual mode of the whole tree from a single prop on aegov-navblock — the markup underneath is identical either way. collapsible (default) shows nested items in an animated accordion, with the active item getting a filled background highlight. flat renders every item at the same indentation level; items with children become non-interactive bold group headers whose children are always visible, and the active item gets a colour/weight change with no background fill.

Dashboard Transactions Account Profile Billing
Dashboard Transactions Account Profile Billing
<aegov-navblock variant="collapsible" block-title="Collapsible">
  <aegov-navblock-item href="/" is-active="true">Dashboard</aegov-navblock-item>
  <aegov-navblock-item href="/transactions">Transactions</aegov-navblock-item>
  <aegov-navblock-item>
    Account
    <aegov-navblock-item href="/account/profile">Profile</aegov-navblock-item>
    <aegov-navblock-item href="/account/billing">Billing</aegov-navblock-item>
  </aegov-navblock-item>
</aegov-navblock>

<aegov-navblock variant="flat" block-title="Flat">
  <aegov-navblock-item href="/" is-active="true">Dashboard</aegov-navblock-item>
  <aegov-navblock-item href="/transactions">Transactions</aegov-navblock-item>
  <aegov-navblock-item>
    Account
    <aegov-navblock-item href="/account/profile">Profile</aegov-navblock-item>
    <aegov-navblock-item href="/account/billing">Billing</aegov-navblock-item>
  </aegov-navblock-item>
</aegov-navblock>

Flat with active border

Add active-border alongside variant="flat" for the Flux sidebar pattern: a persistent light border runs the full height of the list, and the active top-level item's segment of that border switches to the primary colour — a merged active indicator with no layout shift. It has no effect in collapsible mode.

Dashboard Account Profile Billing
<aegov-navblock variant="flat" active-border="true" block-title="Workspace">
  <aegov-navblock-item href="/" is-active="true">Dashboard</aegov-navblock-item>
  <aegov-navblock-item>
    Account
    <aegov-navblock-item href="/account/profile">Profile</aegov-navblock-item>
    <aegov-navblock-item href="/account/billing">Billing</aegov-navblock-item>
  </aegov-navblock-item>
</aegov-navblock>

Block title

block-title renders a short heading above the items. Pass markup via the title slot instead to fully override it — for example to embed an icon next to the title.

Docs API reference Release notes
<aegov-navblock block-title="Resources">
  <aegov-navblock-item href="/docs">Docs</aegov-navblock-item>
  <aegov-navblock-item href="/api">API reference</aegov-navblock-item>
  <aegov-navblock-item href="/releases">Release notes</aegov-navblock-item>
</aegov-navblock>

Single open vs. multiple open

By default, opening one parent closes any other open parent that shares the same direct parent — at every level of the tree. Set is-multiple="true" to allow any number of parents to stay open at once instead.

Reports Sales Inventory Users Admins Members
<aegov-navblock is-multiple="true">
  <aegov-navblock-item>
    Reports
    <aegov-navblock-item href="/r/sales">Sales</aegov-navblock-item>
    <aegov-navblock-item href="/r/inventory">Inventory</aegov-navblock-item>
  </aegov-navblock-item>
  <aegov-navblock-item>
    Users
    <aegov-navblock-item href="/u/admins">Admins</aegov-navblock-item>
    <aegov-navblock-item href="/u/members">Members</aegov-navblock-item>
  </aegov-navblock-item>
</aegov-navblock>

Toggle icon

Switch every parent row's expand/collapse indicator with the icon prop: chevron (default) rotates 180° on open; plus rotates 45° to visually form a cross (×).

Reports Sales
Reports Sales
<aegov-navblock icon="chevron" block-title="Chevron">
  <aegov-navblock-item>
    Reports
    <aegov-navblock-item href="/r/sales">Sales</aegov-navblock-item>
  </aegov-navblock-item>
</aegov-navblock>

<aegov-navblock icon="plus" block-title="Plus">
  <aegov-navblock-item>
    Reports
    <aegov-navblock-item href="/r/sales">Sales</aegov-navblock-item>
  </aegov-navblock-item>
</aegov-navblock>

Sizes

size scales row typography, padding, and icon size. Three tokens are available — sm, base (default), and lg. The parent navblock resolves the token and cascades it to every descendant item. A Tailwind-style responsive string (e.g. "sm md:base xl:lg") is also accepted.

Home Reports
Home Reports
Home Reports
<aegov-navblock size="sm" block-title="Small">
  <aegov-navblock-item href="/" is-active="true">Home</aegov-navblock-item>
  <aegov-navblock-item href="/reports">Reports</aegov-navblock-item>
</aegov-navblock>

<aegov-navblock size="base" block-title="Base">
  <aegov-navblock-item href="/" is-active="true">Home</aegov-navblock-item>
  <aegov-navblock-item href="/reports">Reports</aegov-navblock-item>
</aegov-navblock>

<aegov-navblock size="lg" block-title="Large">
  <aegov-navblock-item href="/" is-active="true">Home</aegov-navblock-item>
  <aegov-navblock-item href="/reports">Reports</aegov-navblock-item>
</aegov-navblock>

Leading icons and inline content

Each item supports a leading icon via slot="icon-start". Anything else placed inside the item — including other components such as aegov-badge — appears inline next to the label, so a count or status pill needs no dedicated slot.

Inbox 12 Sent
<aegov-navblock>
  <aegov-navblock-item href="/inbox" is-active="true">
    <svg slot="icon-start" viewBox="0 0 256 256" aria-hidden="true">
      <rect width="256" height="256" fill="none" />
      <path d="M32 96l96 64 96-64v96a16 16 0 0 1-16 16H48a16 16 0 0 1-16-16Z"
            fill="none" stroke="currentColor" stroke-width="20" stroke-linejoin="round" />
    </svg>
    Inbox
    <aegov-badge variant="primary">12</aegov-badge>
  </aegov-navblock-item>
  <aegov-navblock-item href="/sent">
    <svg slot="icon-start" viewBox="0 0 256 256" aria-hidden="true">
      <rect width="256" height="256" fill="none" />
      <path d="m48 56 176 72-176 72 32-72Z"
            fill="none" stroke="currentColor" stroke-width="20" stroke-linejoin="round" />
    </svg>
    Sent
  </aegov-navblock-item>
</aegov-navblock>

Deep nesting

Sub-items can themselves contain sub-items, recursively. When any descendant item is is-active, every ancestor group is automatically expanded on the initial render, so the active row is visible without any extra code.

Reports Sales Q1 — current Q2 Users Settings
<aegov-navblock>
  <aegov-navblock-item>
    Reports
    <aegov-navblock-item>
      Sales
      <aegov-navblock-item href="/r/sales/q1" is-active="true">Q1 — current</aegov-navblock-item>
      <aegov-navblock-item href="/r/sales/q2">Q2</aegov-navblock-item>
    </aegov-navblock-item>
    <aegov-navblock-item href="/r/users">Users</aegov-navblock-item>
  </aegov-navblock-item>
  <aegov-navblock-item href="/settings">Settings</aegov-navblock-item>
</aegov-navblock>

Bordered

Set is-bordered="true" to wrap the block in a rounded border with internal padding — useful when the block sits directly on a coloured background without its own card frame.

Dashboard Reports
<aegov-navblock is-bordered="true" block-title="Workspace">
  <aegov-navblock-item href="/" is-active="true">Dashboard</aegov-navblock-item>
  <aegov-navblock-item href="/reports">Reports</aegov-navblock-item>
</aegov-navblock>

Disabled items

Set is-disabled to mark an item as unreachable. It renders with reduced opacity, is removed from the tab order (a disabled leaf renders as a non-focusable <span aria-disabled="true">, a disabled parent as a natively disabled <button>), and is skipped entirely by arrow-key navigation. Use it for a step the user cannot reach yet — for example one waiting on a prerequisite.

Step one Step two Step three (locked)
<aegov-navblock>
  <aegov-navblock-item href="/" is-active="true">Step one</aegov-navblock-item>
  <aegov-navblock-item href="/two">Step two</aegov-navblock-item>
  <aegov-navblock-item href="/three" is-disabled="true">Step three (locked)</aegov-navblock-item>
</aegov-navblock>

RTL support

The navblock reads dir="rtl" from the closest ancestor carrying a dir attribute (or the document root if none is set) — the same mechanism used across this design system's other navigation components. The sub-list's connector border, indentation, and active-border segment all mirror automatically through CSS logical properties, and the default label-nav switches to Arabic. Keyboard behaviour does not change with direction: ArrowRight always expands and ArrowLeft always collapses a parent row, and ArrowUp/ArrowDown move between rows.

لوحة التحكم التقارير المبيعات المستخدمون الإعدادات
<div dir="rtl">
  <aegov-navblock block-title="مساحة العمل">
    <aegov-navblock-item href="/" is-active="true">لوحة التحكم</aegov-navblock-item>
    <aegov-navblock-item>
      التقارير
      <aegov-navblock-item href="/r/sales">المبيعات</aegov-navblock-item>
      <aegov-navblock-item href="/r/users">المستخدمون</aegov-navblock-item>
    </aegov-navblock-item>
    <aegov-navblock-item href="/settings">الإعدادات</aegov-navblock-item>
  </aegov-navblock>
</div>

Usage

Here is the recommended usage of a navblock on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.

Mark exactly one item as the current page
Set is-active on the single item matching the current route. If it's nested, its ancestor groups are opened automatically on load so the active row is visible without any extra code.

Choose flat for a short, shallow sidebar and collapsible for a deep one
Flat keeps every item visible at once with bold group headers — good for a handful of sections. Collapsible scales much better once groups start nesting two or three levels deep, since only the relevant branch needs to be open.

Keep one leading icon style consistent across a given navblock
Mixing icon and non-icon top-level items in the same list makes the icon column look accidental rather than intentional. Reserve icons for the top level and skip them on nested sub-items.

Don't set icon, size, or variant directly on an aegov-navblock-item
These cascade automatically from the parent aegov-navblock on every render. Setting them on an individual item works only until the next cascade pass overwrites it.

Don't rely on is-multiple to fix a confusing information architecture
Allowing every group open at once is useful for a short, flat list of independent sections — not as a substitute for restructuring a sidebar where groups are already too deep or too numerous to scan.

Don't use active-border outside of variant="flat"
It has no effect in collapsible mode, which already shows the active item with a filled background highlight instead.

API reference

The following are the properties and references of a navblock

aegov-navblock Properties

AttributeDescriptionTypeDefault

block-title

Heading rendered above the items, as an <h2>. Overridden by the title slot.

string

—

label-nav

Accessible label for the <nav> landmark. Defaults to "Sidebar navigation" (LTR) or "التنقل في الشريط الجانبي" (RTL) when left unset.

string

''

is-multiple

Allow multiple sibling parent items to stay open at once, at every level. When false (default), opening one parent closes any open sibling that shares the same direct parent.

boolean

false

icon

Expand/collapse indicator style for every descendant item.

chevron | plus

'chevron'

size

Size token cascaded to every descendant item. Accepts a single token (sm, base, lg) or a Tailwind-style responsive string.

string

'base'

is-bordered

Wrap the block in a bordered, padded container.

boolean

false

variant

Visual mode cascaded to every descendant item. collapsible shows nested items as an animated accordion; flat renders every item at the same indentation level with non-interactive bold group headers.

collapsible | flat

'collapsible'

active-border

When true and variant="flat", the active top-level item shows a coloured inline-start border segment (Flux sidebar pattern). No effect in collapsible mode.

boolean

false

field-id

DOM id for the <nav> wrapper. Auto-generated if omitted.

string

auto-generated

aegov-navblock-item Properties

AttributeDescriptionTypeDefault

href

Destination URL. Renders an <a> when set and the item has no sub-items.

string

—

target

Anchor target.

_blank | _self | _parent | _top

—

rel

Anchor rel.

string

—

is-active

Marks the item as the current page. Sets aria-current="page" on the link and applies the active visual treatment.

boolean

false

is-disabled

Visually disabled, not focusable, removed from arrow-key navigation. Click is a no-op. A disabled leaf renders as a <span aria-disabled="true"> (even when href is set); a disabled parent row is a natively disabled <button>.

boolean

false

is-open

Whether the sub-region is open. Normally set by the parent navblock as rows toggle; can also be authored directly to open a group by default.

boolean

false

icon, size, variant

Set automatically by the parent aegov-navblock — do not set these directly on an item.

—

—

Slots

ComponentSlotDescription

aegov-navblock

(default)

Top-level aegov-navblock-item children.

aegov-navblock

title

Custom title content. Overrides block-title.

aegov-navblock-item

(default)

Row content — the label, and any inline siblings such as aegov-badge.

aegov-navblock-item

icon-start

Optional leading icon.

aegov-navblock-item

subnav

Nested aegov-navblock-item children. Auto-assigned — a nested item with no explicit slot attribute is promoted into this slot automatically.

Events

EventDetailDescription

aegovNavblockItemToggle

{ open: boolean }

Fired by an aegov-navblock-item when its row toggles the sub-region. The parent aegov-navblock listens for this to enforce single-open behaviour (unless is-multiple) — you do not need to handle it yourself for normal use.

Pass-through attributes

ComponentAttribute groupForwarded?Where applied

aegov-navblock-item

data-*

Yes

Forwarded to the inner item wrapper <div>.

aegov-navblock-item

aria-*

No

Stays on the host <aegov-navblock-item>; not forwarded to the inner row.

aegov-navblock-item

target, rel, referrerpolicy

Yes

Forwarded to the inner <a> link (leaf items only).

aegov-navblock, aegov-navblock-item

class, style, id

Native

Applied to the host element.

Notes

The following notes are applicable of this component.

Built-in accessibility

  • Renders as a <nav> landmark with a configurable aria-label via label-nav, defaulting to "Sidebar navigation" (English) or "التنقل في الشريط الجانبي" (Arabic) when left unset.
  • Items are exposed as a list — the inner container and every sub-region are <div role="list">, and each aegov-navblock-item host carries role="listitem". (Native <ul>/<li> are not used because a list may not contain the custom-element hosts.)
  • Parent rows are real <button> elements with aria-expanded and aria-controls linking the trigger to its sub-region, which is labelled by the trigger (aria-labelledby). A collapsed sub-region is hidden, so its rows are not reachable by Tab.
  • Leaf rows are <a> elements when href is set, or <button> otherwise. The active leaf carries aria-current="page".
  • Disabled items are excluded from both Tab and arrow-key navigation: a disabled parent row is a natively disabled <button>, and a disabled leaf renders as a non-focusable <span aria-disabled="true">.
  • When any descendant item is is-active, every ancestor group is expanded automatically on the initial render, so the active row is never hidden inside a collapsed parent by default.
  • In variant="flat", a group header with children renders as a non-interactive <span role="presentation"> rather than a button, since its children are always visible and there is nothing to toggle.

Developer responsibilities

  • Mark exactly one item per route with is-active.
  • Don't set icon, size, or variant directly on an aegov-navblock-item — they cascade from the parent aegov-navblock on every render and a manual value is overwritten on the next update.
  • Keep a consistent icon/variant choice for a given navblock instance — switching either only visually intended at the whole-tree level.
  • Provide a meaningful label-nav whenever a page has more than one navigation landmark (for example, a navblock sidebar alongside a header navbar).

Keyboard support

Key Action
Tab Move focus to the next visible row. Every link and parent row is its own Tab stop; rows inside a collapsed group and disabled rows are skipped.
ArrowDown Move focus to the next visible row, wrapping to the first.
ArrowUp Move focus to the previous visible row, wrapping to the last.
Home Move focus to the first visible row.
End Move focus to the last visible row.
ArrowRight Expand a closed parent row (focus stays on it). Not swapped in RTL.
ArrowLeft Collapse an open parent row; on a leaf or a closed row, move focus to its parent row instead. Not swapped in RTL.
Enter Follow a leaf link, or toggle a parent row open/closed.
Space Toggle a parent row open/closed (or activate a leaf rendered as a <button>).

Notes

  • A group with children rendered in variant="flat" is always visible — its children are never hidden, and its header is not part of arrow-key navigation (there is nothing to toggle).
  • An unrecognised icon renders the default chevron. An unrecognised variant is not corrected: anything other than flat behaves as collapsible. Both log a console warning in development builds only. An unrecognised size token falls back to base silently.
  • active-border only has a visible effect when variant="flat"; it is otherwise a no-op.