Logo
Neura
Back to Home

Navlist

Navigation list component for creating organized menu items with icons, badges, groups, variants, and colors. Built with accessibility in mind.

Basic Usage

The most basic navlist with simple items: 
<neura::navlist>
    <neura::navlist.item label="Home" href="#" />
    <neura::navlist.item label="About" href="#" />
    <neura::navlist.item label="Contact" href="#" />
</neura::navlist>

With Icons

Add icons to navigation items: 
<neura::navlist>
    <neura::navlist.item label="Home" icon="home" href="#" />
    <neura::navlist.item label="Settings" icon="cog-6-tooth" href="#" />
    <neura::navlist.item label="Profile" icon="user-circle" href="#" />
</neura::navlist>

With Badges

Add badges to display counters or notifications: 
<neura::navlist>
    <neura::navlist.item label="Messages" icon="envelope" badge="5" href="#" />
    <neura::navlist.item label="Notifications" icon="bell" badge="12" href="#" />
</neura::navlist>

Item Variants

Items support two variants: default (subtle background on hover/active) and ghost (text-only, no background).

Default Variant

Ghost Variant 

<neura::navlist.item label="Dashboard" variant="default" />
<neura::navlist.item label="Dashboard" variant="ghost" />

Item Colors

Items support semantic colors: neutral (default), primary, danger, warning, and success. 
<neura::navlist.item label="Dashboard" color="neutral" />
<neura::navlist.item label="Featured" color="primary" />
<neura::navlist.item label="Warnings" color="warning" />
<neura::navlist.item label="Healthy" color="success" />
<neura::navlist.item label="Delete Account" color="danger" />

Active State

The navlist automatically detects the active item based on the current URL. You can also set it manually with :active="true". Active items receive aria-current="page" for accessibility. 
<neura::navlist.item label="Settings" :active="true" />


<neura::navlist.item label="Settings" activePattern="settings/*" />

Groups

Organize items into groups with labels. Group labels are displayed as muted uppercase text for clear section separation. 
<neura::navlist>
    <neura::navlist.group label="Settings">
        <neura::navlist.item label="General" icon="cog-6-tooth" href="#" />
        <neura::navlist.item label="Security" icon="lock-closed" href="#" />
    </neura::navlist.group>
</neura::navlist>

Collapsible Groups

Groups can be made collapsible. The label becomes a button with a rotating chevron and aria-expanded for accessibility. 
<neura::navlist.group label="Settings" :collapsable="true">
    <neura::navlist.item label="General" icon="cog-6-tooth" href="#" />
    <neura::navlist.item label="Security" icon="lock-closed" href="#" />
</neura::navlist.group>

Group Variants

Groups support two variants: default (with left border indent) and compact (minimal indent, no border).

Default Variant

Compact Variant 

<neura::navlist.group label="Settings" variant="default">...</neura::navlist.group>
<neura::navlist.group label="Settings" variant="compact">...</neura::navlist.group>

Group Sizes

Groups support three sizes that control label text size and item spacing: sm, md (default), and lg.
SM
MD (default)
LG 
<neura::navlist.group label="Navigation" size="sm">...</neura::navlist.group>
<neura::navlist.group label="Navigation" size="md">...</neura::navlist.group>
<neura::navlist.group label="Navigation" size="lg">...</neura::navlist.group>

Separator

Use separators between groups or items for visual separation: 
<neura::navlist.item label="Analytics" href="#" />
<neura::navlist.separator />
<neura::navlist.item label="Settings" href="#" />

Label

Standalone section labels for flat navlists without group wrapping: 
<neura::navlist.label>Main</neura::navlist.label>
<neura::navlist.item label="Dashboard" href="#" />

<neura::navlist.separator />

<neura::navlist.label>System</neura::navlist.label>
<neura::navlist.item label="Settings" href="#" />

Complete Example

A full navigation example combining groups, variants, colors, separators, and labels:

Best Practices

Do

  • Use icons to improve visual recognition
  • Organize items into logical groups for clear navigation
  • Use the ghost variant for sub-items or secondary navigation
  • Use color="danger" for destructive actions like "Delete"
  • Use separators to visually distinguish different sections
  • Let the navlist automatically detect the active item based on the URL

Don't

  • Don't create too many levels of nested groups
  • Don't overuse colored items - reserve them for semantic meaning
  • Don't use too many badges - keep them for important information
  • Don't create navlists that are too long - use pagination or sub-menus

Accessibility

The navlist is built with accessibility in mind:
  • Container uses <nav> with aria-label
  • Items are wrapped in <ul> / <li> for proper list semantics
  • Active items receive aria-current="page"
  • Groups use role="group" with aria-labelledby
  • Collapsible groups have aria-expanded on the toggle button
  • All interactive elements have visible focus-visible ring for keyboard navigation
  • Separators use role="separator"

Properties

Navlist Properties

Property Type Default Description
size string 'md' Default size for child items
variant string 'default' Default variant for child items
label string|null null aria-label for the nav element (defaults to "Navigation")

Navlist Item Properties

Property Type Default Description
label string|null null Navigation link text
icon string|null null Icon name to display before the label
badge string|int|null null Badge to display to the right (counter, notification)
href string '#' Link destination URL
active bool|null null Active state (auto-detected from URL if null)
activePattern string|null null URL pattern for active matching (e.g. "settings/*")
variant string 'default' Visual variant: 'default' or 'ghost'
color string 'neutral' Semantic color: 'neutral', 'primary', 'danger', 'warning', 'success'
size string 'md' Item size: 'xs', 'sm', 'md', 'lg', 'xl'

Navlist Group Properties

Property Type Default Description
label string|null null Group label text
icon string|null null Icon displayed before the group label
collapsable bool false Allow collapsing/expanding the group
variant string 'default' Display variant: 'default' or 'compact'
size string 'md' Group size: 'sm', 'md', 'lg'

Navlist Label Properties

Property Type Default Description
size string 'md' Label size: 'sm', 'md', 'lg'