Боковая панель

Боковая панель — колонка навигационных ссылок сбоку от приложения или документации. Она может скрываться совсем или сворачиваться в полоску иконок.

Стабильный

Figma

Обзор

Использование

API

Доступность

Overview

Installation

Foundations

Color

Typography

<tk-sidebar label="Documentation">
  <tk-sidebar-nav-item href="/overview" current>Overview</tk-sidebar-nav-item>
  <tk-sidebar-nav-item href="/install">Installation</tk-sidebar-nav-item>
  <tk-collapsible open>
    <span slot="trigger">Foundations</span>
    <tk-sidebar-nav-item href="/color">Color</tk-sidebar-nav-item>
    <tk-sidebar-nav-item href="/type">Typography</tk-sidebar-nav-item>
  </tk-collapsible>
</tk-sidebar>

Анатомия

Часть	Что это
`tk-sidebar`	панель с тремя областями: `header`, содержимое, `footer`
слот `header`	оформление приложения над ссылками, например логотип или поиск
содержимое	ссылки; ориентир `<nav>`, который прокручивается сам по себе
слот `footer`	оформление приложения под ссылками, например меню аккаунта
`tk-sidebar-nav-item`	одна строка: ссылка или строка, которая раскрывает вложенные строки

Остальное собирайте из других компонентов: группа — это Collapsible, кнопка сворачивания — ваша Icon button, кнопка «ещё» в строке — Menu. Когда ссылки прокручиваются, у края они плавно исчезают; разделительных линий нет.

Строки

Inbox

Starred

Projects Apollo

Borealis

Сворачивание

`collapsible`	Что происходит при сворачивании
`offcanvas` (по умолчанию)	панель уезжает целиком
`icon`	панель сужается до полоски иконок шириной 56px
`none`	не сворачивается

Строки свёрнутой панели выпадают из порядка Tab и из дерева доступности, поэтому в скрытую панель фокусом не попасть.

Полоска иконок

В полоске видны иконки строк верхнего уровня. Для скринридера у каждой строки остаётся имя. Всё, что в содержимом не является строкой, скрыто: подписи групп, поля поиска и обёртки вокруг строк. Поэтому панель с группами лучше сворачивать через offcanvas. Выбирайте иконки, понятные без подписей.

<tk-sidebar id="rail" label="Main" collapsible="icon">
  <tk-sidebar-nav-item href="/inbox"><tk-icon slot="icon" name="mail"></tk-icon>Inbox</tk-sidebar-nav-item>
  <tk-sidebar-nav-item href="/starred"><tk-icon slot="icon" name="star"></tk-icon>Starred</tk-sidebar-nav-item>
</tk-sidebar>
<script>
  document.getElementById('rail').open = false;
</script>

open по умолчанию включён; чтобы панель была свёрнута с самого начала, задайте свойство из скрипта, как выше.

Кнопка сворачивания

Встроенной кнопки нет. Вызывайте toggle() из своей Icon button и называйте её по действию:

<tk-icon-button label="Toggle sidebar" onclick="document.getElementById('nav').toggle()">
  <tk-icon name="menu"></tk-icon>
</tk-icon-button>

Cmd + B на устройствах Apple и Ctrl + B на остальных сворачивают и разворачивают панель с любого места страницы, кроме набора текста в поле. Сочетание меняет hotkey, hotkey="" его выключает. persist запоминает, была ли панель открыта, в localStorage под ключом tk-sidebar:open.

Варианты

Profile

Billing

<tk-sidebar label="Settings" variant="floating">
  <tk-sidebar-nav-item href="/profile" current>Profile</tk-sidebar-nav-item>
  <tk-sidebar-nav-item href="/billing">Billing</tk-sidebar-nav-item>
</tk-sidebar>

sidebar (по умолчанию): прижата к краю окна, с тонкой линией с внутренней стороны.
floating: карточка с отступом от краёв, скруглёнными углами и тенью.

side="right" прикрепляет панель к правому краю.

Раскладка страницы

Панель не сдвигает содержимое страницы. Если она стоит в flex-ряду рядом с содержимым, ничего делать не нужно: страница перестраивается, когда панель сужается. Если вы позиционируете её сами, сдвигайте содержимое теми же переменными, которые читает панель:

.app { --tk-sidebar-width: 260px; --tk-sidebar-rail-width: 56px; }
.app main { margin-inline-start: var(--tk-sidebar-width); }
.app tk-sidebar:not([open]) ~ main { margin-inline-start: 0; }
.app tk-sidebar[collapsible='icon']:not([open]) ~ main { margin-inline-start: var(--tk-sidebar-rail-width); }

Мобильная версия

Навигационное меню на узком экране модальное, поэтому берите Sheet с теми же строками, а панель на этой ширине прячьте. Своей точки перелома у панели нет.

<tk-icon-button label="Open navigation" onclick="document.getElementById('drawer').show()">
  <tk-icon name="menu"></tk-icon>
</tk-icon-button>
<tk-sheet id="drawer" heading="Menu" side="left">
  <tk-sidebar label="Main" collapsible="none">
    <tk-sidebar-nav-item href="/home" current>Home</tk-sidebar-nav-item>
  </tk-sidebar>
</tk-sheet>

Когда использовать

Боковая панель — для основной навигации высокой колонкой рядом со страницей.
Для горизонтального ряда сверху берите Navigation menu.
Для действий берите Menu. Строка панели ведёт куда-то, а не выполняет действие.
Если элементы выбирают или изучают, например файлы, берите Tree.
На узких экранах берите Sheet. Подробнее в разделе Мобильная версия.

Текст

Называйте строку по её странице, заглавная буква только в начале: «Оплата», «Участники команды».
Подписи короткие. Длинная подпись обрезается многоточием.
Не пишите в имени ориентира слово «навигация»: label="Main", а не «Main navigation». Скринридер и так говорит «навигация».

Можно / нельзя

✅ Можно	❌ Нельзя
Ссылки в строках	Действия в строках: для них menu
Свой `label` у каждого `<nav>`	Слово «навигация» в имени
Сворачивать панель с группами через `offcanvas`	Сворачивать панель с группами в полоску иконок
Sheet на узких экранах	Сворачивать панель вместо мобильного меню
Класть строки прямо в панель, которая сворачивается в полоску	Оборачивать строки в другие элементы: полоска их скроет

Navigation menu: основная навигация сверху.
Collapsible: группа строк.
Sheet: меню на узких экранах.
Tree: элементы, которые выбирают или изучают.
Menu: действия.

API

`tk-sidebar`

Атрибут	Тип	По умолчанию	Что делает
`open`	boolean	`true`	развёрнута или свёрнута
`collapsible`	`offcanvas` \| `icon` \| `none`	`offcanvas`	как сворачивается
`variant`	`sidebar` \| `floating`	`sidebar`	прижата к краю или карточка с отступом
`side`	`left` \| `right`	`left`	у какого края стоит
`label`	string	`Main`	имя ориентира `<nav>`
`hotkey`	string	`Mod+B`	сочетание клавиш; `Mod` — это Cmd на устройствах Apple и Ctrl на остальных; `""` выключает
`persist`	boolean	`false`	запоминать `open` в `localStorage`

Слот	Содержимое
`header`	оформление приложения над ссылками
по умолчанию	строки, группы и другое содержимое навигации
`footer`	оформление приложения под ссылками

toggle() сворачивает или разворачивает панель.

`tk-sidebar-nav-item`

Атрибут	Тип	По умолчанию	Что делает
`href`	string	—	делает строку ссылкой; не действует, если у строки есть вложенные
`current`	boolean	`false`	страница, на которой человек сейчас; ставит `aria-current="page"`
`open`	boolean	`false`	раскрыты ли вложенные строки
`disabled`	boolean	`false`	приглушена, вне порядка Tab

Слот	Содержимое
по умолчанию	подпись, обязательна; она же доступное имя
`icon`	один `tk-icon` перед подписью
`trailing`	значок или кнопка «ещё»; в полоске иконок скрыт
`sub`	вложенные строки `tk-sidebar-nav-item`

События

tk-toggle приходит перед тем, как панель свернётся или развернётся; в { open } новое состояние. Отмените событие, чтобы управлять open самим. То же событие отправляют строка с вложенными строками и группа Collapsible, и оба всплывают через панель, поэтому проверяйте источник:

sidebar.addEventListener('tk-toggle', (e) => {
  if (e.target !== sidebar) return;
  save(e.detail.open);
});

CSS

tk-sidebar::part(panel), ::part(header), ::part(content), ::part(footer): панель и три её области.
tk-sidebar-nav-item::part(item), ::part(icon), ::part(label), ::part(trailing), ::part(panel): строка, обёртки её слотов и вложенные строки.
--tk-sidebar-width: ширина развёрнутой панели; по умолчанию 260px.
--tk-sidebar-rail-width: ширина полоски иконок; по умолчанию 56px.

Если меняете стиль подписи, не прячьте её через display: none в полоске иконок: так пропадёт имя строки.

Токены

Часть	Токены
панель	`surface/raised`; `border/subtle` по внутреннему краю
плавающая панель	`surface/raised` + `shadow-2`, `radius-16`, `space-8` от краёв; `border/subtle` только в контрастной теме
строка	`text/default`, Body Small (14/20), `radius-8`, отступы `space-4` / `space-8`, высота от 32px
строка, наведение / нажатие	`state/hover` / `state/press`
текущая строка	`state/on` + `text/accent`, средняя насыщенность; иконка `icon/accent`
иконка	`icon/secondary`, `icon-size-20`
отключённая строка	`text/disabled`
вложенные строки	линия `border/subtle` с начальной стороны
рамка фокуса	`border/accent/focus`

Значения по темам: Color.

Доступность

Встроено:

Содержимое — ориентир <nav> с именем из label. Шапка и подвал в него не входят.
Строки — настоящие ссылки и кнопки, у каждой своя остановка Tab, ролей меню или дерева нет.
current ставит aria-current="page"; строка с вложенными строками сообщает, раскрыта ли она.
Свёрнутая панель выпадает из порядка Tab и из дерева доступности. В полоске иконок строки остаются доступны и сохраняют имена.
Когда ссылки не помещаются, содержимое становится именованной областью прокрутки, на которую можно перейти фокусом.
Сочетание клавиш не срабатывает при наборе текста в полях.

На вашей стороне:

Дайте каждому <nav> на странице свой label, например «Main», «Sections» и «Breadcrumb».
Называйте кнопку сворачивания по действию.
Для мобильного меню берите Sheet.

Клавиша	Действие
`Tab`	переходит по строкам по порядку
`Enter`	открывает ссылку; раскрывает или сворачивает строку с вложенными
`Space`	раскрывает или сворачивает строку с вложенными
`Cmd` / `Ctrl` + `B`	сворачивает или разворачивает панель

Стрелки не используются: это колонка ссылок.

Анатомия

Строки

Сворачивание

Полоска иконок

Кнопка сворачивания

Варианты

Раскладка страницы

Мобильная версия

Когда использовать

Текст

Можно / нельзя

Связанные

API

tk-sidebar

tk-sidebar-nav-item

События

CSS

Токены

Доступность

`tk-sidebar`

`tk-sidebar-nav-item`