Баннер

Баннер — полоса во всю ширину вверху приложения для сообщения обо всём приложении или аккаунте. Внутрь можно положить что угодно.

Стабильный

Figma

Обзор

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

API

Доступность

Your Team trial ends in 3 days. Upgrade

<tk-banner tone="warning" label="Trial ending">
  Your Team trial ends in 3 days.
  <tk-button slot="actions" size="small">Upgrade</tk-button>
</tk-banner>

Анатомия

Часть	Что это
`tk-banner`	сам элемент; во всю ширину
part `banner`	полоса: фон и нижняя граница
part `content`	строка по центру, шириной до `--tk-banner-max-width`
слот и part `icon`	иконка смысла в начале; декоративная
слот по умолчанию (part `body`)	ваше содержимое: текст, ссылка, обратный отсчёт, небольшая форма
слот и part `actions`	действия в конце строки, по желанию
кнопка закрытия	✕, только с `dismissible`

Варианты

We've refreshed the dashboard.

A new version is available.

You're back online.

Maintenance tonight at 22:00 UTC.

Your payment failed. Update your card.

<tk-banner label="Announcement">We've refreshed the dashboard.</tk-banner>
<tk-banner tone="info" label="New version">A new version is available.</tk-banner>
<tk-banner tone="success" label="Connection">You're back online.</tk-banner>
<tk-banner tone="warning" label="Maintenance">Maintenance tonight at 22:00 UTC.</tk-banner>
<tk-banner tone="error" label="Billing">Your payment failed. Update your card.</tk-banner>

neutral (по умолчанию): обычное объявление.
info: сведения или совет.
success: хорошая новость для всего приложения.
warning: предупреждение, например о плановых работах или конце пробного периода.
error: проблема, которую нужно решить, например с оплатой или сетью.

У каждого тона своя форма иконки: треугольник у warning, круг у остальных. Назовите смысл и в тексте: одного цвета мало, его видят не все.

Оформление

treatment="loud" делает полосу инверсной: тёмной в светлой теме и светлой в тёмной. Цвет тона она не берёт, но иконку по-прежнему выбирает тон.

We use cookies to improve your experience. Privacy policy

<tk-banner treatment="loud" label="Cookie notice">
  We use cookies to improve your experience.
  <tk-link slot="actions" href="/privacy" color="inverse">Privacy policy</tk-link>
</tk-banner>

subtle (по умолчанию) — для обычных баннеров, loud — для сообщения, которое должно бросаться в глаза. Сплошной красной или жёлтой полосы нет.

Расположение

static (по умолчанию): баннер стоит в потоке страницы и сдвигает содержимое вниз.
sticky: баннер остаётся вверху при прокрутке и сохраняет своё место.

Полоса занимает всю ширину. Строка с содержимым стоит по центру и не шире 1200px; задайте --tk-banner-max-width по ширине колонки страницы, чтобы текст встал вровень с ней.

Ставьте баннер в начало DOM: так пользователи клавиатуры и скринридера встретят его первым, как и видят. Чтобы закрепить баннер поверх содержимого, оставьте под него место в вёрстке страницы.

Действия

Version 3.2 is ready. What's new

Reload

<tk-banner tone="info" label="New version">
  Version 3.2 is ready.
  <tk-link slot="actions" href="/changelog" treatment="quiet">What's new</tk-link>
  <tk-button slot="actions" size="small">Reload</tk-button>
</tk-banner>

В slot="actions" кладите тихую tk-link или tk-button вида secondary или ghost.
Не больше одного главного и одного второстепенного действия. Если нужно больше, берите диалог или отдельную страницу.
На полосе loud используйте tk-link color="inverse". У кнопок нет инверсного вида, и на такой полосе им может не хватить контраста.

Закрытие

You're back online.

<tk-banner tone="success" label="Connection" dismissible>You're back online.</tk-banner>

dismissible добавляет ✕ с именем из dismiss-label. Нажатие запускает отменяемое событие tk-dismiss, и баннер прячется сам, если вы не вызвали preventDefault().

banner.addEventListener('tk-dismiss', (event) => {
  event.preventDefault();
  saveDismissed('maintenance');
  banner.remove();
});

Не давайте закрыть баннер, если пользователь обязан на него отреагировать, например при заблокированном аккаунте.
Если фокус был на баннере, после закрытия переведите его в разумное место.

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

Баннер — для сообщения обо всём приложении: плановые работы, конец пробного периода, нет сети, новая версия, уведомление о cookie.
Для заметки об одной части страницы берите Section message. Они уживаются на одном экране: баннер об оплате вверху и заметка о счёте внутри страницы оплаты.
Для короткого подтверждения, которое исчезнет само, есть Toast.
Если пользователь должен что-то сделать, прежде чем продолжить, нужен Dialog. Баннер ничего не блокирует и не забирает фокус.
Показывайте один баннер за раз. Какой из них важнее, решает ваше приложение.

Текст

Скажите, что случилось или что предстоит, и что делать, в одном-двух предложениях.
Если есть срок, назовите дату: «Пробный период закончится в понедельник. Оформите подписку, чтобы сохранить проекты».
Действие называет следующий шаг: «Обновить карту», «Перезагрузить». Никогда не «ОК».

Подробнее в Messages.

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

✅ Можно	❌ Нельзя
Сообщение обо всём приложении	Заметка об одном разделе; для неё есть section message
Один баннер за раз	Несколько баннеров друг над другом
`live`, если баннер добавлен после загрузки	Объявлять баннер, который был при загрузке
Диалог, если сначала нужно действие	Давать закрыть баннер, требующий действия
`tk-link color="inverse"` на полосе `loud`	Ставить баннеру `role="banner"`

Section message: сообщение внутри содержимого страницы.
Toast: короткое сообщение, которое исчезает само.
Dialog: сообщение, которое блокирует работу до действия.
Button и Link: что кладут в actions.

API

Атрибуты

Атрибут	Тип	По умолчанию	Что делает
`tone`	`neutral` \| `info` \| `success` \| `warning` \| `error`	`neutral`	смысл: оттенок, иконка и граница
`treatment`	`subtle` \| `loud`	`subtle`	тонированная или инверсная полоса
`placement`	`static` \| `sticky`	`static`	в потоке или закреплён вверху при прокрутке
`live`	`off` \| `polite` \| `assertive`	`off`	объявить баннер, добавленный после загрузки
`label`	string	`""`	доступное имя; делает баннер именованной областью
`dismissible`	boolean	`false`	показывает ✕
`dismiss-label`	string	`"Dismiss"`	доступное имя ✕
`hide-icon`	boolean	`false`	убирает иконку смысла

Слоты

Слот	Содержимое
по умолчанию	сообщение: любое содержимое
`icon`	заменяет иконку смысла; скрыт от скринридеров
`actions`	ссылки и кнопки в конце строки

События

Событие	Что означает
`tk-dismiss`	нажали ✕; отменяемое, баннер прячется, если вы не отменили событие

CSS

Parts: banner, content, icon, body, actions.
--tk-banner-max-width: наибольшая ширина строки с содержимым, по умолчанию 1200px.

Токены

Оформление / тон	Заливка	Текст	Иконка	Нижняя граница
subtle, `neutral`	`surface/sunken`	`text/secondary`	`icon/secondary`	`border/default`
subtle, `info` · `success` · `warning` · `error`	`surface/{tone}`	`text/{tone}`	`icon/{tone}`	`border/{tone}`
`loud`	`surface/inverse`	`text/inverse`	`icon/inverse`	нет

sticky использует z-sticky. На полосе loud рамка фокуса border/inverse. Значения по темам: Color.

Доступность

Встроено:

Никогда не role="banner": это ориентир шапки страницы. Если его задать, баннер его уберёт.
С label баннер становится именованной областью, к которой можно перейти скринридером. Без него это обычный контейнер.
По умолчанию баннер не объявляется; если он есть при загрузке, его читают по порядку.
live="polite" даёт ему role="status", live="assertive" — role="alert".
Баннер не забирает фокус. У ✕ есть доступное имя, а иконка смысла скрыта.
Текст не ниже 4.5:1, иконка не ниже 3:1 во всех тонах и темах.

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

Задайте label без слова «баннер»: «Плановые работы», а не «Баннер о плановых работах».
Выберите live по тому, как появляется баннер: off при загрузке страницы, polite для новостей, добавленных позже, assertive только для срочного, например потери сети.
Ставьте баннер в начало DOM.
Называйте смысл словами.

Анатомия

Варианты

Оформление

Расположение

Действия

Закрытие

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

Текст

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

Связанные

API

Атрибуты

Слоты

События

CSS

Токены

Доступность