ki-popover
@kimen/elements/ki-popover- Source
- Agent reference
Use a popover for filters, details or a small form that belongs beside a trigger. Use ki-dialog when the user must make a decision, and ki-tooltip for a short hover or focus hint.
<ki-button id="incident-filters" type="button" variant="secondary">Filters</ki-button><ki-popover for="incident-filters" label="Incident filters"><ki-checkbox checked>Open incidents</ki-checkbox><ki-checkbox>Assigned to me</ki-checkbox></ki-popover>Trigger and keyboard behavior
Give the trigger a unique id and pass it to for. Put both elements in the same document or shadow tree. If the trigger is inside a form, use type="button" so activation leaves the form untouched.
Opening a dialog popover focuses an available control inside it. Tab can reach the rest of the page. Escape closes the popover and returns focus to the trigger. A click outside also closes it.
Toggletip
Use kind="toggletip" for supplemental text. Screen readers receive the text as a polite status update and the trigger keeps focus.
<ki-button id="retention-info" type="button" variant="ghost">About retention</ki-button><ki-popover for="retention-info" kind="toggletip" placement="bottom" arrow="false">Logs are kept for 30 days.</ki-popover>Rich toggletip
Set appearance="rich" for a short explanation with actions. Click or
press Enter to open the named non-modal dialog and move focus inside it.
Escape closes it and returns focus to the trigger.
Kimen follows the system setting.
<ki-button id="contrast-info" type="button" variant="ghost">Contrast mode</ki-button><ki-popover for="contrast-info" kind="toggletip" appearance="rich" label="About contrast mode" arrow="false"><strong>Contrast mode</strong><p>Kimen follows the system setting.</p><ki-button type="button" size="sm" variant="ghost">Learn more</ki-button></ki-popover>The rich appearance shares the --ki-tooltip-rich-* tokens with
ki-tooltip. Use a direct <strong> child for the styled heading.
Placement and styling
The default placement is bottom-start. Use top, bottom, start or end, with optional -start or -end alignment. The popover flips when the opposite side has more room. Use arrow="false" to hide the arrow.
Restyle the panel with the --ki-popover-* tokens or the surface and arrow parts. The surface has no animation.
API reference
When to use: Show filters, details, a small form, or an explanation opened by click. Use a rich toggletip for a short explanation with actions.
When not to use: Use ki-dialog for required decisions and ki-tooltip for hover or focus hints.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
appearance | appearance | "default" | "rich" | undefined | 'default' | Rich shares the tooltip's raised surface, body and heading styles. With kind="toggletip" it enables actions and moves focus inside on open. |
arrow | arrow | boolean | true | Shows the arrow toward the trigger. |
for | for | string | undefined | – | ID of the button in the same document or shadow tree. |
kind | kind | "dialog" | "toggletip" | 'dialog' | Use dialog for controls or toggletip for supplemental information. Rich toggletips can contain actions. |
label | label | string | undefined | 'Popover' | Accessible name of a dialog popover. |
open | open | boolean | false | Visibility. Reflects activation and native dismissal. |
placement | placement | "bottom" | "bottom-end" | "bottom-start" | "end" | "end-end" | "end-start" | "start" | "start-end" | "start-start" | "top" | "top-end" | "top-start" | 'bottom-start' | Preferred side and logical alignment. Flips when room is limited. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-close | CustomEvent<void> | Emitted when the popover closes. |
ki-open | CustomEvent<void> | Emitted when the popover opens. |
Slots
| Slot | Description |
|---|---|
| (default) | Dialog content or toggletip text. A rich toggletip also accepts actions. |
CSS parts
| Part | Description |
|---|---|
arrow | The decorative arrow. |
surface | The popover panel. |
CSS custom properties
The public styling contract of ki-popover: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-popover-arrow-size | Side length of an anchored surface pointer before rotation. |
--ki-popover-backdrop-filter | Complete backdrop filter behind an anchored surface. |
--ki-popover-bg | Raised popover surface colour. |
--ki-popover-bg-image | Optional image layer over an anchored surface colour. |
--ki-popover-border | Popover outline colour. |
--ki-popover-border-width | Outline thickness for a small anchored surface. |
--ki-popover-fg | Popover content ink. |
--ki-popover-gap | Space between a floating surface and its trigger. |
--ki-popover-max-width | Maximum inline size of a small anchored surface. |
--ki-popover-padding | Interior padding for a small anchored surface. |
--ki-popover-radius | Corner radius for a small anchored surface. |
--ki-popover-shadow | Popover elevation. |
--ki-tooltip-rich-backdrop-filter | Complete backdrop filter of the rich surface. |
--ki-tooltip-rich-bg | Fill of the rich tooltip or rich popover. |
--ki-tooltip-rich-bg-image | Optional image layer over the rich surface fill. |
--ki-tooltip-rich-border-color | Outline ink of the rich surface. |
--ki-tooltip-rich-border-width | Outline thickness of the rich surface. |
--ki-tooltip-rich-fg | Ink of the rich surface body text. |
--ki-tooltip-rich-font-size | Body text size of the rich surface. |
--ki-tooltip-rich-font-weight | Body text weight of the rich surface. |
--ki-tooltip-rich-heading-family | Typeface of the rich surface heading. |
--ki-tooltip-rich-heading-fg | Ink of the rich surface heading over the shared fill. |
--ki-tooltip-rich-heading-gap | Distance between the rich heading and its body. |
--ki-tooltip-rich-heading-size | Text size of the rich surface heading. |
--ki-tooltip-rich-heading-weight | Text weight of the rich surface heading. |
--ki-tooltip-rich-line-height | Body text line height of the rich surface. |
--ki-tooltip-rich-max-width | Maximum inline size of the rich surface. |
--ki-tooltip-rich-padding-block | Block-axis inset of the rich surface, before density scaling. |
--ki-tooltip-rich-padding-inline | Inline-axis inset of the rich surface, before density scaling. |
--ki-tooltip-rich-radius | Corner radius of the rich surface. |
--ki-tooltip-rich-shadow | Raised elevation of the rich surface. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-para | semantic dimension for typography line height para. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |