Topbar is a toolbar that always remains visible on the page and provides quick access to navigation and controls.

example icon
Dashboards

Depending on the interface requirements, it may include a logo, a title, breadcrumbs, action buttons, and other elements.

This content option is suitable for initial screens when there is no need to display the navigation path. Mark the title with [kbqTopBarTitle]: it has the same size as size="big" breadcrumbs, so a page that switches between the two keeps the bar height and the text position. Add kbq-truncate-line to keep a long title on one line; without it the title wraps and the bar grows with it.

example icon
Dashboards

If you need to display the number of objects on the current page, you can do so by showing a special counter next to the page title:

example icon
Dashboards13,294

For internal pages of a specific module, using Breadcrumbs is an excellent option. This helps users navigate the application more easily.

On the right side of the toolbar, there is a dedicated area for placing any actions that need to be displayed on the current page.

We recommend using the following set of actions (from left to right):

  • Indicators (e.g., data refresh indicator)
  • A group of icon buttons (e.g., filters)
  • Frequently used actions as buttons (e.g., "Add...", "Share")
  • Additional actions in a dropdown menu, where all secondary actions related to the current page can be placed.
Actions

Internal elements can adjust to the toolbar size.

The minimum allowed spacing between the left side and the right side with actions is 80px and is defined using the CSS variable --kbq-top-bar-spacer-min-width.

When the panel is compressed, the breadcrumbs will adjust as follows:

The automatic breadcrumb shortening is used as the basis, where middle items are hidden when there is not enough free space.
example icon
If the space becomes even narrower, the leftmost breadcrumb level is also hidden, leaving only the rightmost level visible.
example icon
The minimum width of the left side depends on the title of the current item, which can be truncated to 3 characters with an ellipsis (…).
example icon
After reaching the minimum width on the left side, the compression of the right side with actions can begin.
example icon

The variant using only the page title will adjust as follows:

When there is free space, the title and actions are fully displayed.
example icon
Page Header10
The minimum width of the left side depends on the page title, which can be truncated to 3 characters with the addition of three dots (…).
example icon
Page Header10
After reaching the minimum width of the left side, you can start compressing the right side with the actions.
example icon
Page Header10

A more detailed explanation of breadcrumb compression is provided on the Breadcrumbs page.

The toolbar can remain fixed while scrolling the page.

Page13,294
Description NASA describes a case where a person accidentally ended up in an area close to a vacuum (pressure below 1 Pa) due to an air leak from a spacesuit. StatusBadgeAdditional Information Space is an endless expanse full of mysteries and wonders. It begins beyond our atmosphere and stretches to the farthest corners of the Universe. In space, there are billions of stars, planets, and galaxies, each with its own unique story and characteristics. Exploring space helps us better understand not only the Universe itself but also our place within it.

One of the most fascinating aspects of space is its infinity. Scientists still cannot determine exactly where the Universe ends. There are theories that it may be infinite or have certain boundaries. This opens up many questions about what lies beyond the visible universe and what forms of life might exist on other planets. Space research also plays a crucial role in the development of technologies on Earth. Many inventions we use in everyday life were developed thanks to space programs. For example, satellite navigation, communication systems, and even some medical technologies have their roots in space exploration. This shows how studying space can benefit humanity as a whole. Finally, space inspires creativity and dreams. Since childhood, we have looked at the stars and wondered what might exist beyond our planet. Movies, books, and art often draw inspiration from space, creating images that capture the imagination. This drive for exploration and discovery makes space not only a scientific but also a cultural part of our lives.

The example above keeps the toolbar outside the scrolling area, which needs no configuration at all. To make the toolbar itself stick, set --kbq-top-bar-inset-block-start: 0 on it and put it inside the scrolling element: --kbq-top-bar-position is already sticky, but a sticky box is only offset once it has an inset, so with the default auto the toolbar lays out exactly like position: relative.

Panels opened from the page content paint above the toolbar. To have them slide under it, see Panels under a sticky header.

The inputs cover the shadow and the accessible name; everything else is configured through custom properties set on kbq-top-bar itself. The defaults are declared on the element, so a value set on an ancestor does not reach it.

VariableDefaultDescription
--kbq-top-bar-z-index990Layer of the toolbar: above page content and the kbqOverlayLayer layer (980), below the CDK overlay container (1000).
--kbq-top-bar-positionstickyposition of the host. On its own it changes nothing — see --kbq-top-bar-inset-block-start.
--kbq-top-bar-inset-block-startautoDistance a sticky toolbar keeps from the top of its scrolling ancestor. auto imposes no constraint, so the toolbar does not stick.
--kbq-top-bar-padding-verticalvar(--kbq-size-m)Vertical padding of the toolbar.
--kbq-top-bar-padding-horizontalvar(--kbq-size-xxl)Horizontal padding of the toolbar.
--kbq-top-bar-border-radius0Corner radius of the toolbar.
--kbq-top-bar-title-heightvar(--kbq-size-3xl)Minimum height of [kbqTopBarTitle], the box of a size="big" breadcrumb item.
--kbq-top-bar-spacer-min-width80pxWidth of [kbqTopBarSpacer], the guaranteed clearance between the two sides.
--kbq-top-bar-container-start-min-width0Width the start container never shrinks below. Set it whenever the left-hand content has to stay readable in a narrow toolbar.
--kbq-top-bar-container-start-gap0Gap between the elements of the start container.
--kbq-top-bar-container-end-gapvar(--kbq-size-s)Gap between the elements of the end container, and between the overflowing action buttons.
--kbq-top-bar-backgroundvar(--kbq-background-bg)Background of the toolbar.
--kbq-top-bar-shadow-bottomvar(--kbq-shadow-overflow-normal-bottom)Shadow drawn while withShadow is set.
--kbq-top-bar-shadow-transitionease-out 300msTransition of that shadow.

kbq-top-bar ships without a landmark role on purpose: the same toolbar is the page header in one place and a panel header in another, and a page may expose only one banner. Pick the semantics at the call site.

When the toolbar is the page header, give it the banner landmark — wrapping it in a <header> that is not nested in <main>, <article> or <section> does the same thing:

<kbq-top-bar role="banner">…</kbq-top-bar>

Whenever a page renders more than one toolbar, name each of them so assistive technology can tell them apart:

<kbq-top-bar role="banner" aria-label="Dashboards">…</kbq-top-bar>

Use role="toolbar" only if the toolbar implements roving focus itself: a toolbar is expected to be a single tab stop whose controls are reached with the arrow keys. Without that, leave the buttons as ordinary tab stops. The icon-only buttons a toolbar usually carries — the overflow trigger included — need an aria-label of their own, which the toolbar cannot supply.

Suggestions for improvement
If you found a mistake or want to improve the article, create an issue on GitHub.