Logo
Neura UI
Loading…
Logo
All pages 86

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:
blade 
<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:
blade 
<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:
blade 
<neura::navlist>
    <neura::navlist.item label="Messages" icon="envelope" badge="5" href="#" />
    <neura::navlist.item label="Notifications" icon="bell" badge="12" href="#" />
</neura::navlist>

Navlist Variants

Set variant on neura::navlist to style all items (default, ghost, soft, rail). Items can still override with their own variant.
blade
DEFAULT 
<neura::navlist variant="default">...</neura::navlist>
blade
GHOST 
<neura::navlist variant="ghost">...</neura::navlist>
blade
SOFT 
<neura::navlist variant="soft">...</neura::navlist>
blade
RAIL 
<neura::navlist variant="rail">...</neura::navlist>

Item Colors

Items support semantic colors: neutral (default), primary, danger, warning, and success.
blade 
<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.
blade 
<neura::navlist.item label="Settings" :active="true" />


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

Groups

Organize items into groups with labels. Group labels accept a label prop or an x-slot:label for custom content.
blade 
<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.group>
        <x-slot:label>
            <span class="flex items-center gap-1.5">
                Account
                <neura::badge size="sm" color="primary">New</neura::badge>
            </span>
        </x-slot:label>
        <neura::navlist.item label="Profile" icon="user-circle" href="#" />
        <neura::navlist.item label="Billing" icon="credit-card" 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.
blade 
<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

Group layout is independent from item styles: default, compact, separated (hairline under label), and card (inset panel).
blade
DEFAULT 
<neura::navlist.group label="Settings" variant="default">...</neura::navlist.group>
blade
COMPACT 
<neura::navlist.group label="Settings" variant="compact">...</neura::navlist.group>
blade
SEPARATED 
<neura::navlist.group label="Settings" variant="separated">...</neura::navlist.group>
blade
CARD 
<neura::navlist.group label="Settings" variant="card">...</neura::navlist.group>

Group Sizes

Groups support three sizes that control label text size and item spacing: sm, md (default), and lg.
blade
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:
blade 
<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:
blade 
<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 ghost or rail for quieter 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' Item style inherited by children: 'default', 'ghost', 'soft', 'rail'
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', 'ghost', 'soft', 'rail' (inherits from navlist)
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|slot|null null Group label text, or custom content via x-slot:label
icon string|null null Icon displayed before the group label
collapsable bool false Allow collapsing/expanding the group
variant string 'default' Layout variant: 'default', 'compact', 'separated', 'card'
size string 'md' Group size: 'sm', 'md', 'lg'

Navlist Label Properties

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