ki-counter
@kimen/elements/ki-counter- Source
- Agent reference
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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
dot | dot | boolean | false | Show a dot independently of the count, including when the value is zero. |
for | for | string | 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. |
max | max | number | 99 | Largest count displayed in full. Higher values display the cap with a plus sign. Fractional caps round down; invalid caps use 99. |
tone | tone | "danger" | "neutral" | "primary" | "success" | 'danger' | Semantic palette of the pill or dot. An unknown tone uses danger. |
value | value | number | undefined | – | Count of unread or pending items. Finite values are rounded down. Values below one and non-finite values hide the count. |
CSS parts
| Part | Description |
|---|---|
indicator | Painted 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.
| Token | Description |
|---|---|
--ki-counter-backdrop-filter | Complete backdrop filter for the indicator. |
--ki-counter-bg | Danger notification indicator fill. |
--ki-counter-bg-image | Optional image over the notification indicator fill. |
--ki-counter-dot-size | Width and height of the presence dot. |
--ki-counter-fg | Danger notification count text. |
--ki-counter-font-family | Font family for the count. |
--ki-counter-font-size | Font size for the count. |
--ki-counter-font-weight | Font weight for the count. |
--ki-counter-neutral-bg | Neutral notification indicator fill. |
--ki-counter-neutral-fg | Neutral notification count text. |
--ki-counter-padding-inline | Horizontal padding of a count pill. |
--ki-counter-primary-bg | Primary notification indicator fill. |
--ki-counter-primary-fg | Primary notification count text. |
--ki-counter-radius | Radius of the painted pill or dot. |
--ki-counter-ring | Surface-colored ring that separates the indicator from the trigger. |
--ki-counter-ring-width | Thickness of the separating ring. |
--ki-counter-size | Minimum width and height of a count pill. |
--ki-counter-success-bg | Success notification indicator fill. |
--ki-counter-success-fg | Success notification count text. |