NavigationRail

Navigation rails let people switch between UI views on mid-sized devices.

One family, one doc

NavigationRail, NavigationRailItem, and NavigationRailSection form a single family. This page is their shared documentation; each component keeps its own API reference:

NavigationRail provides primary navigation for an app on mid-sized devices. Compose it with NavigationRailItem children; optionally include a Fab and NavigationRailSection labels.

import {
  NavigationRail,
  NavigationRailItem,
} from '@udixio/ui-react';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';

export default function NavigationRailBasicReact() {
  return (
    <NavigationRail className="bg-surface-container-highest h-[500px]">
      <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} selected>
        Alarm
      </NavigationRailItem>
      <NavigationRailItem icon={iSchedule} iconSelected={iSchedule}>
        Clock
      </NavigationRailItem>
      <NavigationRailItem icon={iHourglass} iconSelected={iHourglass}>
        Timer
      </NavigationRailItem>
      <NavigationRailItem icon={iTimer} iconSelected={iTimer}>
        Stopwatch
      </NavigationRailItem>
    </NavigationRail>
  );
}

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { NavigationRail, NavigationRailItem } from '@udixio/ui-angular';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';

@Component({
  selector: 'docs-navigation-rail-basic-angular',
  standalone: true,
  imports: [NavigationRail, NavigationRailItem],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <udx-navigation-rail class="bg-surface-container-highest h-[500px]">
      <udx-navigation-rail-item [icon]="iNotifications" [iconSelected]="iNotifications" label="Alarm" selected />
      <udx-navigation-rail-item [icon]="iSchedule" [iconSelected]="iSchedule" label="Clock" />
      <udx-navigation-rail-item [icon]="iHourglass" [iconSelected]="iHourglass" label="Timer" />
      <udx-navigation-rail-item [icon]="iTimer" [iconSelected]="iTimer" label="Stopwatch" />
    </udx-navigation-rail>
  `,
})
export class NavigationRailBasicAngular {
  protected readonly iNotifications = iNotifications;
  protected readonly iSchedule = iSchedule;
  protected readonly iHourglass = iHourglass;
  protected readonly iTimer = iTimer;
}

<script lang="ts">
  import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
  import { iNotifications } from '@udixio/icons-rounded-400/notifications';
  import { iSchedule } from '@udixio/icons-rounded-400/schedule';
  import { iTimer } from '@udixio/icons-rounded-400/timer';
  import { NavigationRail, NavigationRailItem } from '@udixio/ui-svelte';
</script>

<NavigationRail class="bg-surface-container-highest h-[500px]">
  <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} selected>Alarm</NavigationRailItem>
  <NavigationRailItem icon={iSchedule} iconSelected={iSchedule}>Clock</NavigationRailItem>
  <NavigationRailItem icon={iHourglass} iconSelected={iHourglass}>Timer</NavigationRailItem>
  <NavigationRailItem icon={iTimer} iconSelected={iTimer}>Stopwatch</NavigationRailItem>
</NavigationRail>

Alignment

alignment distributes items either from the top ("top", default) or spread across the rail’s full height ("middle").

import {
  NavigationRail,
  NavigationRailItem,
} from '@udixio/ui-react';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';

export default function NavigationRailAlignmentReact() {
  return (
    <div className="h-[500px] flex gap-8">
      <NavigationRail className="bg-surface-container-highest" alignment="top">
        <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} selected>
          Alarm
        </NavigationRailItem>
        <NavigationRailItem icon={iSchedule} iconSelected={iSchedule}>
          Clock
        </NavigationRailItem>
        <NavigationRailItem icon={iHourglass} iconSelected={iHourglass}>
          Timer
        </NavigationRailItem>
        <NavigationRailItem icon={iTimer} iconSelected={iTimer}>
          Stopwatch
        </NavigationRailItem>
      </NavigationRail>
      <NavigationRail className="bg-surface-container-highest" alignment="middle">
        <NavigationRailItem
          icon={iNotifications}
          iconSelected={iNotifications}
          label="Alarm"
          selected
        />
        <NavigationRailItem icon={iSchedule} iconSelected={iSchedule} label="Clock" />
        <NavigationRailItem icon={iHourglass} iconSelected={iHourglass} label="Timer" />
        <NavigationRailItem icon={iTimer} iconSelected={iTimer} label="Stopwatch" />
      </NavigationRail>
    </div>
  );
}

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { NavigationRail, NavigationRailItem } from '@udixio/ui-angular';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';

@Component({
  selector: 'docs-navigation-rail-alignment-angular',
  standalone: true,
  imports: [NavigationRail, NavigationRailItem],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="h-[500px] flex gap-8">
      <udx-navigation-rail class="bg-surface-container-highest" alignment="top">
        <udx-navigation-rail-item [icon]="iNotifications" [iconSelected]="iNotifications" label="Alarm" selected />
        <udx-navigation-rail-item [icon]="iSchedule" [iconSelected]="iSchedule" label="Clock" />
        <udx-navigation-rail-item [icon]="iHourglass" [iconSelected]="iHourglass" label="Timer" />
        <udx-navigation-rail-item [icon]="iTimer" [iconSelected]="iTimer" label="Stopwatch" />
      </udx-navigation-rail>
      <udx-navigation-rail class="bg-surface-container-highest" alignment="middle">
        <udx-navigation-rail-item [icon]="iNotifications" [iconSelected]="iNotifications" label="Alarm" selected />
        <udx-navigation-rail-item [icon]="iSchedule" [iconSelected]="iSchedule" label="Clock" />
        <udx-navigation-rail-item [icon]="iHourglass" [iconSelected]="iHourglass" label="Timer" />
        <udx-navigation-rail-item [icon]="iTimer" [iconSelected]="iTimer" label="Stopwatch" />
      </udx-navigation-rail>
    </div>
  `,
})
export class NavigationRailAlignmentAngular {
  protected readonly iNotifications = iNotifications;
  protected readonly iSchedule = iSchedule;
  protected readonly iHourglass = iHourglass;
  protected readonly iTimer = iTimer;
}

<script lang="ts">
  import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
  import { iNotifications } from '@udixio/icons-rounded-400/notifications';
  import { iSchedule } from '@udixio/icons-rounded-400/schedule';
  import { iTimer } from '@udixio/icons-rounded-400/timer';
  import { NavigationRail, NavigationRailItem } from '@udixio/ui-svelte';
</script>

<div class="h-[500px] flex gap-8">
  <NavigationRail class="bg-surface-container-highest" alignment="top">
    <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} selected>Alarm</NavigationRailItem>
    <NavigationRailItem icon={iSchedule} iconSelected={iSchedule}>Clock</NavigationRailItem>
    <NavigationRailItem icon={iHourglass} iconSelected={iHourglass}>Timer</NavigationRailItem>
    <NavigationRailItem icon={iTimer} iconSelected={iTimer}>Stopwatch</NavigationRailItem>
  </NavigationRail>
  <NavigationRail class="bg-surface-container-highest" alignment="middle">
    <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} label="Alarm" selected />
    <NavigationRailItem icon={iSchedule} iconSelected={iSchedule} label="Clock" />
    <NavigationRailItem icon={iHourglass} iconSelected={iHourglass} label="Timer" />
    <NavigationRailItem icon={iTimer} iconSelected={iTimer} label="Stopwatch" />
  </NavigationRail>
</div>

Extended rail

Toggling the extended mode reveals labels and any NavigationRailSection. Control it with extended/onExtendedChange (extendedChange in Angular, or bind:extended in Svelte), or leave it uncontrolled with defaultExtended. A Fab placed as a direct child is hoisted into the rail’s header; Angular does not clone it, so pass its extended state explicitly.

import { useState } from 'react';
import {
  Fab,
  NavigationRail,
  NavigationRailItem,
  NavigationRailSection,
} from '@udixio/ui-react';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';
import { iCalendarMonth } from '@udixio/icons-rounded-400/calendar_month';
import { iShowChart } from '@udixio/icons-rounded-400/show_chart';
import { iMusicNote } from '@udixio/icons-rounded-400/music_note';
import { iAdd } from '@udixio/icons-rounded-400/add';

export default function NavigationRailExtendedReact() {
  const [extended, setExtended] = useState(true);

  return (
    <NavigationRail
      className="bg-surface-container-highest h-[750px]"
      extended={extended}
      onExtendedChange={setExtended}
    >
      <Fab label="Add Timer" icon={iAdd} extended={extended} />
      <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} label="Alarm" />
      <NavigationRailItem icon={iSchedule} iconSelected={iSchedule} label="Clock" />
      <NavigationRailItem icon={iHourglass} iconSelected={iHourglass} label="Timer" />
      <NavigationRailItem icon={iTimer} iconSelected={iTimer} label="Stopwatch" />
      <NavigationRailSection label="Sleep well" />
      <NavigationRailItem label="Schedule" icon={iCalendarMonth} iconSelected={iCalendarMonth} />
      <NavigationRailItem label="Stats" icon={iShowChart} iconSelected={iShowChart} />
      <NavigationRailItem label="Sleep sound" icon={iMusicNote} iconSelected={iMusicNote} />
    </NavigationRail>
  );
}

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  Fab,
  NavigationRail,
  NavigationRailItem,
  NavigationRailSection,
} from '@udixio/ui-angular';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';
import { iCalendarMonth } from '@udixio/icons-rounded-400/calendar_month';
import { iShowChart } from '@udixio/icons-rounded-400/show_chart';
import { iMusicNote } from '@udixio/icons-rounded-400/music_note';
import { iAdd } from '@udixio/icons-rounded-400/add';

@Component({
  selector: 'docs-navigation-rail-extended-angular',
  standalone: true,
  imports: [NavigationRail, NavigationRailItem, NavigationRailSection, Fab],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <udx-navigation-rail
      class="bg-surface-container-highest h-[750px]"
      [extended]="extended()"
      (extendedChange)="extended.set($event)"
    >
      <udx-fab label="Add Timer" [icon]="iAdd" [extended]="extended()" />
      <udx-navigation-rail-item [icon]="iNotifications" [iconSelected]="iNotifications" label="Alarm" />
      <udx-navigation-rail-item [icon]="iSchedule" [iconSelected]="iSchedule" label="Clock" />
      <udx-navigation-rail-item [icon]="iHourglass" [iconSelected]="iHourglass" label="Timer" />
      <udx-navigation-rail-item [icon]="iTimer" [iconSelected]="iTimer" label="Stopwatch" />
      <udx-navigation-rail-section label="Sleep well" />
      <udx-navigation-rail-item [icon]="iCalendarMonth" [iconSelected]="iCalendarMonth" label="Schedule" />
      <udx-navigation-rail-item [icon]="iShowChart" [iconSelected]="iShowChart" label="Stats" />
      <udx-navigation-rail-item [icon]="iMusicNote" [iconSelected]="iMusicNote" label="Sleep sound" />
    </udx-navigation-rail>
  `,
})
export class NavigationRailExtendedAngular {
  protected readonly extended = signal(true);
  protected readonly iNotifications = iNotifications;
  protected readonly iSchedule = iSchedule;
  protected readonly iHourglass = iHourglass;
  protected readonly iTimer = iTimer;
  protected readonly iCalendarMonth = iCalendarMonth;
  protected readonly iShowChart = iShowChart;
  protected readonly iMusicNote = iMusicNote;
  protected readonly iAdd = iAdd;
}

<script lang="ts">
  import { iAdd } from '@udixio/icons-rounded-400/add';
  import { iCalendarMonth } from '@udixio/icons-rounded-400/calendar_month';
  import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
  import { iMusicNote } from '@udixio/icons-rounded-400/music_note';
  import { iNotifications } from '@udixio/icons-rounded-400/notifications';
  import { iSchedule } from '@udixio/icons-rounded-400/schedule';
  import { iShowChart } from '@udixio/icons-rounded-400/show_chart';
  import { iTimer } from '@udixio/icons-rounded-400/timer';
  import { Fab, NavigationRail, NavigationRailItem, NavigationRailSection } from '@udixio/ui-svelte';

  let extended = $state(true);
</script>

<NavigationRail class="bg-surface-container-highest h-[750px]" bind:extended>
  {#snippet fab()}
    <Fab label="Add Timer" icon={iAdd} {extended} />
  {/snippet}
  <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} label="Alarm" />
  <NavigationRailItem icon={iSchedule} iconSelected={iSchedule} label="Clock" />
  <NavigationRailItem icon={iHourglass} iconSelected={iHourglass} label="Timer" />
  <NavigationRailItem icon={iTimer} iconSelected={iTimer} label="Stopwatch" />
  <NavigationRailSection label="Sleep well" />
  <NavigationRailItem label="Schedule" icon={iCalendarMonth} iconSelected={iCalendarMonth} />
  <NavigationRailItem label="Stats" icon={iShowChart} iconSelected={iShowChart} />
  <NavigationRailItem label="Sleep sound" icon={iMusicNote} iconSelected={iMusicNote} />
</NavigationRail>

Controlled selection

Use selectedItem to control the selected item. React exposes a raw setSelectedItem dispatcher; Angular follows this repository’s output convention with selectedItemChange ([(selectedItem)] also works). Svelte uses bind:selectedItem or selectedItem with onSelectedItemChange. onItemSelected/itemSelected notifies with the resulting index, label, and icon.

import { useState } from 'react';
import {
  Fab,
  NavigationRail,
  NavigationRailItem,
} from '@udixio/ui-react';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';
import { iAdd } from '@udixio/icons-rounded-400/add';

export default function NavigationRailSelectionReact() {
  const [index, setIndex] = useState<number | null>(0);

  return (
    <NavigationRail
      className="bg-surface-container-highest h-[750px]"
      selectedItem={index}
      setSelectedItem={setIndex}
    >
      <Fab label="Add Timer" icon={iAdd} />
      <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} label="Alarm" />
      <NavigationRailItem icon={iSchedule} iconSelected={iSchedule} label="Clock" />
      <NavigationRailItem icon={iHourglass} iconSelected={iHourglass} label="Timer" />
      <NavigationRailItem icon={iTimer} iconSelected={iTimer} label="Stopwatch" />
    </NavigationRail>
  );
}

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { Fab, NavigationRail, NavigationRailItem } from '@udixio/ui-angular';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iTimer } from '@udixio/icons-rounded-400/timer';
import { iAdd } from '@udixio/icons-rounded-400/add';

@Component({
  selector: 'docs-navigation-rail-selection-angular',
  standalone: true,
  imports: [NavigationRail, NavigationRailItem, Fab],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <udx-navigation-rail
      class="bg-surface-container-highest h-[750px]"
      [selectedItem]="index()"
      (selectedItemChange)="index.set($event)"
    >
      <udx-fab label="Add Timer" [icon]="iAdd" />
      <udx-navigation-rail-item [icon]="iNotifications" [iconSelected]="iNotifications" label="Alarm" />
      <udx-navigation-rail-item [icon]="iSchedule" [iconSelected]="iSchedule" label="Clock" />
      <udx-navigation-rail-item [icon]="iHourglass" [iconSelected]="iHourglass" label="Timer" />
      <udx-navigation-rail-item [icon]="iTimer" [iconSelected]="iTimer" label="Stopwatch" />
    </udx-navigation-rail>
  `,
})
export class NavigationRailSelectionAngular {
  protected readonly index = signal(0);
  protected readonly iNotifications = iNotifications;
  protected readonly iSchedule = iSchedule;
  protected readonly iHourglass = iHourglass;
  protected readonly iTimer = iTimer;
  protected readonly iAdd = iAdd;
}

<script lang="ts">
  import { iAdd } from '@udixio/icons-rounded-400/add';
  import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
  import { iNotifications } from '@udixio/icons-rounded-400/notifications';
  import { iSchedule } from '@udixio/icons-rounded-400/schedule';
  import { iTimer } from '@udixio/icons-rounded-400/timer';
  import { Fab, NavigationRail, NavigationRailItem } from '@udixio/ui-svelte';

  let selectedItem = $state<number | null>(0);
</script>

<NavigationRail class="bg-surface-container-highest h-[750px]" bind:selectedItem>
  {#snippet fab()}
    <Fab label="Add Timer" icon={iAdd} />
  {/snippet}
  <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} label="Alarm" />
  <NavigationRailItem icon={iSchedule} iconSelected={iSchedule} label="Clock" />
  <NavigationRailItem icon={iHourglass} iconSelected={iHourglass} label="Timer" />
  <NavigationRailItem icon={iTimer} iconSelected={iTimer} label="Stopwatch" />
</NavigationRail>

Footer content

footer pins arbitrary content — an account menu, a sign-out button — below the item list, without wrapping NavigationRail in a custom layout. In Angular, add a footer attribute to the projected element.

import { IconButton, NavigationRail, NavigationRailItem } from '@udixio/ui-react';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iLogout } from '@udixio/icons-rounded-400/logout';

export default function NavigationRailFooterReact() {
  return (
    <NavigationRail
      className="bg-surface-container-highest h-[500px]"
      footer={<IconButton icon={iLogout} label="Sign out" />}
    >
      <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} selected>
        Alarm
      </NavigationRailItem>
      <NavigationRailItem icon={iSchedule} iconSelected={iSchedule}>
        Clock
      </NavigationRailItem>
      <NavigationRailItem icon={iHourglass} iconSelected={iHourglass}>
        Timer
      </NavigationRailItem>
    </NavigationRail>
  );
}

import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
  IconButton,
  NavigationRail,
  NavigationRailItem,
} from '@udixio/ui-angular';
import { iNotifications } from '@udixio/icons-rounded-400/notifications';
import { iSchedule } from '@udixio/icons-rounded-400/schedule';
import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
import { iLogout } from '@udixio/icons-rounded-400/logout';

@Component({
  selector: 'docs-navigation-rail-footer-angular',
  standalone: true,
  imports: [NavigationRail, NavigationRailItem, IconButton],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <udx-navigation-rail class="bg-surface-container-highest h-[500px]">
      <udx-icon-button footer [icon]="iLogout" label="Sign out" />
      <udx-navigation-rail-item [icon]="iNotifications" [iconSelected]="iNotifications" label="Alarm" selected />
      <udx-navigation-rail-item [icon]="iSchedule" [iconSelected]="iSchedule" label="Clock" />
      <udx-navigation-rail-item [icon]="iHourglass" [iconSelected]="iHourglass" label="Timer" />
    </udx-navigation-rail>
  `,
})
export class NavigationRailFooterAngular {
  protected readonly iNotifications = iNotifications;
  protected readonly iSchedule = iSchedule;
  protected readonly iHourglass = iHourglass;
  protected readonly iLogout = iLogout;
}

<script lang="ts">
  import { iHourglass } from '@udixio/icons-rounded-400/hourglass';
  import { iLogout } from '@udixio/icons-rounded-400/logout';
  import { iNotifications } from '@udixio/icons-rounded-400/notifications';
  import { iSchedule } from '@udixio/icons-rounded-400/schedule';
  import { IconButton, NavigationRail, NavigationRailItem } from '@udixio/ui-svelte';
</script>

<NavigationRail class="bg-surface-container-highest h-[500px]">
  {#snippet footer()}
    <IconButton icon={iLogout} label="Sign out" />
  {/snippet}
  <NavigationRailItem icon={iNotifications} iconSelected={iNotifications} selected>Alarm</NavigationRailItem>
  <NavigationRailItem icon={iSchedule} iconSelected={iSchedule}>Clock</NavigationRailItem>
  <NavigationRailItem icon={iHourglass} iconSelected={iHourglass}>Timer</NavigationRailItem>
</NavigationRail>

Composition

NavigationRailItem is a single destination; it renders a link when href is set, otherwise a button. The selected item exposes aria-current="page".
NavigationRailSection is a non-interactive label that groups the items following it; it, and any item placed after it, only render while the rail is extended.
A Fab placed as a direct child is hoisted into the rail’s header and collapses/expands with the rail.

Angular differences

NavigationRailItem’s label reveal (width/height + opacity) is driven by a shared @udixio/core/dom Motion controller, identical in both frameworks.
Angular does not clone the projected Fab; bind its extended input explicitly from the same state driving the rail (see the example above).