@softwarity/rail-nav

Material Design 3 Navigation Rail component for Angular. Extends Angular Material mat-sidenav to provide a collapsible rail navigation pattern.

Live Demo

Features

Material Design 3 - Implements the Navigation Rail pattern from MD3
Extends Material - Built on top of MatSidenav for reliability
Navigation Items - rail-nav-item component with MD3 pill animation, badges, and router support
Contextual Drawer - [for] on an item opens a side drawer from an <ng-template>, with hover-intent, content cross-fade, outside-tap dismiss and mobile support
Separator & Spacer - rail-nav-separator to group items, rail-nav-spacer to anchor items at the bottom
Expand/Collapse - Smooth transition between rail and drawer with adaptive width
Backdrop - Optional backdrop overlay when expanded
Position - Support for left (start) or right (end) positioning
Dark Mode - Automatically adapts to light/dark color scheme
SCSS Theming - Customizable via SCSS mixin following Angular Material pattern

Installation

npm install @softwarity/rail-nav

Peer Dependencies

Package	Version
@angular/common	>= 21.0.0
@angular/core	>= 21.0.0
@angular/cdk	>= 21.0.0
@angular/material	>= 21.0.0

Usage

Import the components in your Angular component:

import {
  RailnavComponent,
  RailnavContainerComponent,
  RailnavContentComponent,
  RailnavItemComponent,
  RailnavSeparatorComponent, // Optional: separator between item groups
  RailnavSpacerComponent,    // Optional: push following items to the bottom
  RailnavBrandingDirective   // Optional: for custom branding
} from '@softwarity/rail-nav';

@Component({
  imports: [
    RailnavComponent,
    RailnavContainerComponent,
    RailnavContentComponent,
    RailnavItemComponent,
    RailnavSeparatorComponent,
    RailnavSpacerComponent,
    RailnavBrandingDirective
  ],
  template: `
    <rail-nav-container>
      <rail-nav title="My App" subtitle="v1.0">
        <rail-nav-item label="Home" routerLink="/home">
          <mat-icon>home</mat-icon>
        </rail-nav-item>
        <rail-nav-item label="Settings" routerLink="/settings">
          <mat-icon>settings</mat-icon>
        </rail-nav-item>
      </rail-nav>
      <rail-nav-content>
        <!-- Page content -->
      </rail-nav-content>
    </rail-nav-container>
  `
})
export class AppComponent {}

API

RailnavComponent

The main navigation rail component. Extends MatSidenav.

Input	Type	Default	Description
`position`	`'start' \| 'end'`	`'start'`	Position of the rail (left or right)
`title`	`string`	-	Title displayed next to burger when expanded
`subtitle`	`string`	-	Subtitle displayed below title when expanded
`hideDefaultHeader`	`boolean`	`false`	Hide the default header to provide custom content
`autoCollapse`	`boolean`	`true`	Auto-collapse the rail when an item is clicked

Property/Method	Type	Description
`expanded`	`Signal<boolean>`	Read the current expanded state
`toggleExpanded()`	`void`	Toggle between collapsed and expanded
`expand()`	`void`	Expand the rail
`collapse()`	`void`	Collapse the rail

RailnavContainerComponent

Container component. Extends MatSidenavContainer.

Input	Type	Default	Description
`showBackdrop`	`boolean`	`true`	Show backdrop overlay when expanded

RailnavContentComponent

Content area component. Extends MatSidenavContent.

Note: When placed inside a rail-nav-container alongside a rail-nav, the component automatically detects the rail position and applies the correct margin using the --rail-nav-collapsed-width CSS variable.

RailnavItemComponent

Navigation item with MD3 pill animation.

Input	Type	Default	Description
`routerLink`	`string \| any[]`	-	Router link for navigation
`label`	`string`	-	Label text (below icon when collapsed, beside when expanded)
`badge`	`string \| number \| boolean`	-	Badge value. Use `true` for a small dot badge
`active`	`boolean`	`false`	Whether this item is active (for non-router usage)
`for`	`TemplateRef \| null`	`null`	Template projected as a contextual drawer when the item is hovered or clicked. Aliased to `for` for `mat-datepicker-toggle`-style ergonomics. See Contextual drawer.

Output	Type	Description
`itemClick`	`void`	Emitted when clicked (automatically collapses rail)

RailnavSeparatorComponent

Visual separator between groups of <rail-nav-item>. Hairline 1px rule, vertically centered in a fixed-height host so the spacing stays consistent across collapsed / expanded modes.

<rail-nav>
  <rail-nav-item label="Home">...</rail-nav-item>
  <rail-nav-separator />
  <rail-nav-item label="Trash">...</rail-nav-item>
</rail-nav>

Color overridable via --rail-nav-separator-color.

RailnavSpacerComponent

Flexible spacer (flex: 1 1 auto). Place between two groups of items to push everything after it to the bottom of the rail — the classic pattern for primary nav on top and Settings / Profile anchored at the bottom.

<rail-nav>
  <rail-nav-item label="Home">...</rail-nav-item>
  <rail-nav-item label="Inbox">...</rail-nav-item>
  <rail-nav-spacer />
  <rail-nav-item label="Settings">...</rail-nav-item>
</rail-nav>

Contextual drawer

Any rail item can declare a contextual side drawer with [for]="someTemplate". The library renders the template in a CDK overlay positioned right next to the rail, handles hover-intent (200ms), close debounce (300ms for cursor transit), outside-tap dismiss, auto-close when the rail is expanded, and re-targets the same overlay when the cursor moves between trigger items.

import {
  RailnavComponent,
  RailnavContainerComponent,
  RailnavContentComponent,
  RailnavItemComponent,
} from '@softwarity/rail-nav';

@Component({
  imports: [
    RailnavComponent,
    RailnavContainerComponent,
    RailnavContentComponent,
    RailnavItemComponent,
  ],
  template: `
    <rail-nav-container>
      <rail-nav>
        <rail-nav-item label="Workspaces" [for]="wsTpl">
          <mat-icon>workspaces</mat-icon>
        </rail-nav-item>
      </rail-nav>
      <rail-nav-content>...</rail-nav-content>
    </rail-nav-container>

    <ng-template #wsTpl>
      <a routerLink="/ws/1">Workspace 1</a>
      <a routerLink="/ws/2">Workspace 2</a>
    </ng-template>
  `,
})
export class AppComponent {}

The drawer panel applies its own chrome (background, shadow, rounded right corner) and a default nav-list layout (flex column, padding, gap, fixed width) — your template only needs the children. Both desktop hover and mobile tap open the drawer; the lib swallows the synthetic mouse events touch devices fire after a tap so the drawer doesn't close instantly.

Drawer CSS custom properties

Override per rail (or globally) — all read with sane Material defaults as fallback.

Variable	Default	Description
`--rail-nav-drawer-width`	`240px`	Fixed drawer width
`--rail-nav-drawer-padding`	`12px`	Inner padding
`--rail-nav-drawer-gap`	`4px`	Vertical gap between children
`--rail-nav-drawer-surface`	`var(--mat-sys-surface)`	Background color
`--rail-nav-drawer-on-surface`	`var(--mat-sys-on-surface)`	Text color
`--rail-nav-drawer-shadow`	`var(--mat-sys-level2)`	Elevation
`--rail-nav-drawer-radius`	`0 12px 12px 0`	Outer border-radius

SCSS Theming

Use the SCSS mixin to customize colors following the Angular Material pattern:

@use '@softwarity/rail-nav/rail-nav-theme' as rail-nav;

:root {
  @include rail-nav.overrides((
    backdrop-color: rgba(0, 0, 0, 0.5),
    primary: #6200ea,
    surface-color: #f5f5f5,
  ));
}

Available Tokens

Token	Default	Description
`collapsed-width`	`72px`	Width of the rail when collapsed
`expanded-width`	`fit-content`	Width of the rail when expanded
`header-height`	`56px`	Height of the header area
`backdrop-color`	-	Background color for the backdrop overlay
`surface-color`	-	Background color for the rail
`surface-container-high`	-	Background color for hover states
`on-surface`	-	Text color for primary content
`on-surface-variant`	-	Text color for secondary content
`secondary-container`	-	Background color for active items
`on-secondary-container`	-	Text color for active items
`primary`	-	Focus ring color
`error`	-	Badge background color
`on-error`	-	Badge text color

CSS Custom Properties

You can also use CSS custom properties directly.

Size Properties

:root {
  --rail-nav-collapsed-width: 72px;
  --rail-nav-expanded-width: fit-content;
  --rail-nav-header-height: 56px;
}

Color Properties

Color properties support the CSS light-dark() function for automatic light/dark theme adaptation:

:root {
  /* Static colors (single theme) */
  --rail-nav-surface-color: #ffffff;
  --rail-nav-primary: #6750a4;

  /* Or use light-dark() for automatic theme adaptation */
  --rail-nav-surface-color: light-dark(#ffffff, #1e1e1e);
  --rail-nav-primary: light-dark(#6750a4, #d0bcff);
}

The component uses Material Design 3 system tokens (--mat-sys-*) as fallbacks.

Light/Dark Theme Support

Use the CSS light-dark() function to define colors that automatically adapt to the user's color scheme. The first value is for light mode, the second for dark mode.

With SCSS mixin

@use '@softwarity/rail-nav/rail-nav-theme' as rail-nav;

:root {
  @include rail-nav.overrides((
    backdrop-color: light-dark(rgba(0, 0, 0, 0.4), rgba(0, 0, 0, 0.6)),
    surface-color: light-dark(#ffffff, #1e1e1e),
    on-surface: light-dark(#1c1b1f, #e6e1e5),
    primary: light-dark(#6750a4, #d0bcff),
  ));
}

With CSS custom properties

:root {
  --rail-nav-backdrop-color: light-dark(rgba(0, 0, 0, 0.4), rgba(0, 0, 0, 0.6));
  --rail-nav-surface-color: light-dark(#ffffff, #1e1e1e);
  --rail-nav-on-surface: light-dark(#1c1b1f, #e6e1e5);
  --rail-nav-on-surface-variant: light-dark(#49454f, #cac4d0);
  --rail-nav-secondary-container: light-dark(#e8def8, #4a4458);
  --rail-nav-on-secondary-container: light-dark(#1d192b, #e8def8);
  --rail-nav-primary: light-dark(#6750a4, #d0bcff);
  --rail-nav-error: light-dark(#b3261e, #f2b8b5);
  --rail-nav-on-error: light-dark(#ffffff, #601410);
}

Setting up color-scheme

For light-dark() to work, set the color-scheme property on your document:

html {
  color-scheme: light;
  &.dark-mode { color-scheme: dark; }
}

/* Or use system preference */
html {
  color-scheme: light dark;
}

Example

@Component({
  imports: [
    RailnavComponent,
    RailnavContainerComponent,
    RailnavContentComponent,
    RailnavItemComponent,
    MatIconModule
  ],
  template: `
    <rail-nav-container [showBackdrop]="true">
      <rail-nav title="My App" subtitle="v1.0">
        <rail-nav-item label="Home" [badge]="3" routerLink="/home">
          <mat-icon>home</mat-icon>
        </rail-nav-item>
        <rail-nav-item label="Favorites" [badge]="true" routerLink="/favorites">
          <mat-icon>favorite</mat-icon>
        </rail-nav-item>
        <rail-nav-item label="Settings" routerLink="/settings">
          <mat-icon>settings</mat-icon>
        </rail-nav-item>
      </rail-nav>
      <rail-nav-content>
        <main>Your content here</main>
      </rail-nav-content>
    </rail-nav-container>
  `
})
export class MyComponent {}

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
assets		assets
projects/demo		projects/demo
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
angular.json		angular.json
karma.conf.js		karma.conf.js
ng-package.json		ng-package.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.lib.json		tsconfig.lib.json
tsconfig.lib.prod.json		tsconfig.lib.prod.json
tsconfig.spec.json		tsconfig.spec.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

@softwarity/rail-nav

Features

Installation

Peer Dependencies

Usage

API

RailnavComponent

RailnavContainerComponent

RailnavContentComponent

RailnavItemComponent

RailnavSeparatorComponent

RailnavSpacerComponent

Contextual drawer

Drawer CSS custom properties

SCSS Theming

Available Tokens

CSS Custom Properties

Size Properties

Color Properties

Light/Dark Theme Support

With SCSS mixin

With CSS custom properties

Setting up color-scheme

Example

License

About

Uh oh!

Releases

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@softwarity/rail-nav

Features

Installation

Peer Dependencies

Usage

API

RailnavComponent

RailnavContainerComponent

RailnavContentComponent

RailnavItemComponent

RailnavSeparatorComponent

RailnavSpacerComponent

Contextual drawer

Drawer CSS custom properties

SCSS Theming

Available Tokens

CSS Custom Properties

Size Properties

Color Properties

Light/Dark Theme Support

With SCSS mixin

With CSS custom properties

Setting up color-scheme

Example

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages