Skip to content
Kimenpre-v1documentation home
Color scheme

ki-counter

Use a counter for unread or pending items on a trigger, or for presence on an avatar. Use ki-badge for object status and text or ki-badge for a count within a list row.

Theme for this example
Color scheme for this example
<ki-icon-button variant="secondary" label="Messages, 120 unread">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
<path d="M3 4h18v12H9l-6 4V4Z" stroke-width="2" stroke-linejoin="round" />
</svg>
<ki-counter slot="counter" value="120"></ki-counter>
</ki-icon-button>
<ki-avatar initials="AG" label="Ana García, online">
<ki-counter slot="counter" tone="success" dot></ki-counter>
</ki-avatar>

A count of zero hides the pill. Values above max display the cap with a plus sign. Set dot for a marker without digits. The tone defaults to danger and also accepts primary, success, and neutral.

Accessible placement

Use the counter slot on ki-icon-button or ki-avatar. For an external trigger such as a link, set for to its ID in the same document or shadow root.

<a id="inbox-link" href="/inbox" aria-label="Inbox, 120 unread">Inbox</a>
<ki-counter for="inbox-link" value="120"></ki-counter>
<p id="inbox-updates" role="status"></p>

Include the meaning in the trigger’s accessible name. For important changes, update a pre-existing polite status region once with the localized message.

API reference

When to use: mark unread or pending items on a trigger, or presence on an avatar. Supply the full meaning in the host's accessible name and use a page-owned polite live region for important updates.

When not to use: for an object's status (use ki-badge), a count inside a list row (use text or ki-badge), or an announcement that needs its own semantics.

Properties & attributes

AttributePropertyTypeDefaultDescription
dotdotbooleanfalseShow a dot independently of the count, including when the value is zero.
forforstring | undefined–Literal ID of a trigger in the same document or shadow root. Places the indicator at its block-start inline-end corner and hides it while the trigger is unavailable. For a named host slot, omit this property.
maxmaxnumber99Largest count displayed in full. Higher values display the cap with a plus sign. Fractional caps round down; invalid caps use 99.
tonetone"danger" | "neutral" | "primary" | "success"'danger'Semantic palette of the pill or dot. An unknown tone uses danger.
valuevaluenumber | undefined–Count of unread or pending items. Finite values are rounded down. Values below one and non-finite values hide the count.

CSS parts

PartDescription
indicatorPainted pill or dot, including the surrounding ring.

CSS custom properties

The public styling contract of ki-counter: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-counter-backdrop-filterComplete backdrop filter for the indicator.
--ki-counter-bgDanger notification indicator fill.
--ki-counter-bg-imageOptional image over the notification indicator fill.
--ki-counter-dot-sizeWidth and height of the presence dot.
--ki-counter-fgDanger notification count text.
--ki-counter-font-familyFont family for the count.
--ki-counter-font-sizeFont size for the count.
--ki-counter-font-weightFont weight for the count.
--ki-counter-neutral-bgNeutral notification indicator fill.
--ki-counter-neutral-fgNeutral notification count text.
--ki-counter-padding-inlineHorizontal padding of a count pill.
--ki-counter-primary-bgPrimary notification indicator fill.
--ki-counter-primary-fgPrimary notification count text.
--ki-counter-radiusRadius of the painted pill or dot.
--ki-counter-ringSurface-colored ring that separates the indicator from the trigger.
--ki-counter-ring-widthThickness of the separating ring.
--ki-counter-sizeMinimum width and height of a count pill.
--ki-counter-success-bgSuccess notification indicator fill.
--ki-counter-success-fgSuccess notification count text.

Workshop

Open ki-counter in Storybook