Data and Identity

Stable - @kikita-labs/ui v2.0.0

Scrollbar

Token-driven native scrollbar styling. Not a component: a CSS utility class plus an app-wide provider option.

Import

Load the Kikita stylesheet once. Scrollbar has no directive or component to import.

scrollbar.ts
import '@kikita-labs/ui/styles/kikita-ui.css';

Usage

Apply the kui-scroll class to the element that actually scrolls for local, per-container opt-in styling.

Scrollbar has no playground on this page. Its only public surface is the .kui-scroll class and the provideKikitaUi({ scrollbars }) provider option—there are no component inputs to toggle in an interactive playground, so this page covers both directly with a rendered example and code snippets instead.

First paragraph of scrollable content.

Second paragraph of scrollable content.

Third paragraph of scrollable content.

Fourth paragraph of scrollable content.

Fifth paragraph of scrollable content.

<div class="kui-scroll local-scroll-container-example__region" tabindex="0">
  <p>First paragraph of scrollable content.</p>
  <p>Second paragraph of scrollable content.</p>
  <p>Third paragraph of scrollable content.</p>
  <p>Fourth paragraph of scrollable content.</p>
  <p>Fifth paragraph of scrollable content.</p>
</div>

App-wide styled scrollbars

Set scrollbars: 'styled' once in app config to style native scrollbars across application-owned scroll containers. Defaults to 'native'. Kikita-owned overlays (dropdown, dialog, drawer, command palette) already use Kikita scrollbar tokens regardless of this setting.

app.config.ts.ts
import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [provideKikitaUi({ scrollbars: 'styled' })],
};

Custom scrollbars

Kikita styles the native scrollbar and does not ship a replacement.

A custom track built from CSS anchor positioning and scroll timelines still needs JavaScript for dragging, and animation-range is not Baseline yet. Kikita does not hide the native scrollbar or expose a custom-scrollbar API until the design need, supported browsers, drag and pointer cancellation, zoom, nested scrolling, RTL, forced colors, SSR and fallback have been reviewed. Native token styling is the supported contract.

API

CSS custom properties and provider option verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
.kui-scrollCSS class — Local opt-in for Kikita scrollbar token styling. Apply to the element that actually scrolls (the one with overflow: auto/scroll set), not a non-scrolling wrapper.
provideKikitaUi({ scrollbars })KuiScrollbarMode = 'native' | 'styled''native'App-wide scrollbar mode for application-owned scroll containers. Sets data-kui-scrollbars on the document root. Kikita-owned internal scroll areas (dropdown, dialog body, drawer body, command palette list) use Kikita scrollbar tokens automatically regardless of this option.
--kui-scrollbar-sizeCSS custom property — Scrollbar thickness.
--kui-scrollbar-radiusCSS custom property — Corner radius of the scrollbar thumb.
--kui-scrollbar-trackCSS custom property — Scrollbar track background color.
--kui-scrollbar-thumb-minCSS custom property — Minimum thumb length so short thumbs stay grabbable.
--kui-scrollbar-thumb-insetCSS custom property — Inset spacing between the thumb and the track edge.
--kui-color-scrollbar-thumbCSS custom property — Thumb color in the resting state.
--kui-color-scrollbar-thumb-hoverCSS custom property — Thumb color on hover.
--kui-color-scrollbar-thumb-activeCSS custom property — Thumb color while being dragged.

Accessibility

Scrollbar only restyles native browser scrolling; it does not change scroll behavior or semantics.

  • Keyboard scrolling, touch scrolling, and assistive-technology behavior remain owned by the native scroll container.
  • Add tabindex="0" on the scrollable element itself so keyboard users can focus and scroll it (WCAG 2.1.1, axe scrollable-region-focusable); CSS alone cannot make an overflow container focusable.
  • Do not add ARIA roles solely to style a scrollbar.
  • In forced-colors mode, scrollbar colors fall back to the system implementation.
  • Browser and OS scrollbar rendering can differ, especially with overlay scrollbars.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Scrollbar.

  • provideKikitaUi({ scrollbars }) now sets data-kui-scrollbars on the server as well, so server-rendered HTML carries the mode.
  • The scrollbar thumb roles derive from seeds.neutral together with the surface, border and text roles.
  • The scrollbar stylesheet moved beside the other primitives and is still included through @kikita-labs/ui/styles.