Kit part · Navigation · Sidebars

Icon rail

A narrow sidebar of icon keys, using the kit’s own icons. A lamp beside the current one is lit, a label shows as a tooltip on hover and on focus, and a key at the foot opens the rail out so every label is printed beside its icon. It remembers which way you left it.

Element: <tui-icon-rail>
Needs: kit.css + kit.mjs
Rules: icon-rail.rules.md · 6
Finishes: Aluminium · Graphite · Porcelain · Black
Volumes: Tactile · Quiet

On this page

Variants
Every state, at once
API
Markup
Accessibility
How it’s built
Rules
Related parts

Variants

Closed

Open · expanded

Three items

No foot key

Every state, at once

Both finishes, side by side. Hover, pressed and focus are forced with .is-hover, .is-down and .is-focus; checked and disabled are real.

Aluminium

Part	Closed	Hover	Tooltip	Key focus	Open
Icon rail	Files Inbox	Files Inbox	Files Inbox	Files Inbox	Files Inbox

Graphite

Part	Closed	Hover	Tooltip	Key focus	Open
Icon rail	Files Inbox	Files Inbox	Files Inbox	Files Inbox	Files Inbox

API

Name	Kind	Values	What it does
<tui-icon-rail>	element	expanded · remember	The plate. expanded: labels printed beside the icons. remember: a name to keep the choice under in localStorage, as “tui-icon-rail:<name>”.
nav.tui-icon-rail__nav	element	aria-label	The landmark. Name it: “Workspace”.
a.tui-icon-rail__item	element	href · aria-current	An icon key that is a link. aria-current="page" lets it into the plate and lights its lamp.
.tui-icon-rail__label	class	text	The item’s name. A tooltip when the rail is closed and printed when it is open. It stays in the page either way, so the icon is always named.
button.tui-key.tui-icon-rail__toggle	element	at the foot	Opens and closes the rail and stays down while it is open. Its own label reads “Show labels” or “Hide labels”.
expanded	property	boolean	Read or set whether the labels are printed. Setting it stores the choice.
tui-icon-rail	event	detail.expanded	When the foot key or the property changes it. Bubbles.
--ir-item	custom property	length	The height of an item and of the foot key: 44px.
.is-hover · .is-tip · .is-focus · .is-current	class	on an item	Docs only: force a state.
↑ ↓ · Home · End	keyboard	on a key	Move between the icon keys and the foot key. Tab visits each one as well.

Markup

<tui-icon-rail remember="workspace">
  <nav class="tui-icon-rail__nav" aria-label="Workspace">
    <ul class="tui-icon-rail__list">
      <li><a class="tui-icon-rail__item" href="/files" aria-current="page">
        <svg class="tui-icon" …/><span class="tui-icon-rail__label">Files</span>
      </a></li>
      <li><a class="tui-icon-rail__item" href="/inbox">
        <svg class="tui-icon" …/><span class="tui-icon-rail__label">Inbox</span>
      </a></li>
      …
    </ul>
  </nav>
  <button class="tui-key tui-icon-rail__toggle" type="button">
    <svg class="tui-icon" …/><span class="tui-icon-rail__label">Show labels</span>
  </button>
</tui-icon-rail>

import { icon } from '/kit/kit.mjs';   // the icons; also defines <tui-icon-rail>

item.innerHTML = icon('folder') + '<span class="tui-icon-rail__label">Files</span>';

const rail = document.querySelector('tui-icon-rail');
rail.expanded = true;                       // print the labels
rail.addEventListener('tui-icon-rail', (e) => e.detail.expanded);

// remember="workspace" keeps the choice in localStorage as "tui-icon-rail:workspace".
// Where storage is refused, the rail starts as it was marked up.

Needs kit.css and kit.mjs. How to install the kit.

Every item is a link whose name is its label, which is always in the page: closed, the label is a tooltip made visible, not added, so an icon on its own is never the only name.
The tooltip shows on hover and on keyboard focus, and on a touch screen a press goes straight to the link, where the page’s own heading says where you are.
The current item has aria-current="page" and a lit lamp, and is let into the plate; the lamp is colour, the aria attribute and the sunk key are not.
The foot key is a real button whose name says what it will do (“Show labels”, “Hide labels”). Opening the rail moves nothing: icons stay where they were and only the words appear.
The choice is stored in localStorage, read and written inside try/catch; a browser that refuses storage starts the rail as it was marked up.
With reduced motion the rail opens at once, without easing, and the tooltip appears without sliding.

How it’s built

A plate with an 8px edge and a 12px margin on its left for the lamps, so the current item’s lamp sits beside it like the full side rail’s. An item is 44px square, and its 6px corner and the 8px edge make the plate’s 12px. Closed, the label is a small contrast plate set to the right and made visible on hover and focus; it is never removed from the page, only made transparent, which is why the icon key still has a name. Opened, the same label loses its plate and sits in the row, and the icon does not move: the item’s padding is the half of the closed width the icon was centred in. The width eases; everything else follows from an attribute, and the foot key is the one control that needs a script.

Rules

icon-rail.rules.mdIn the brain

The narrow sidebar of an app, where the icons are known and the width is precious.

6 rules in this file, with the foundations they rest on and the anti-patterns that break them. Full rules ship in the brain with the Pass.

See the Founder Pass How agents use the brain