ki-link
@kimen/elements/ki-link- Source
- Agent reference
Use ki-link for navigation. Use ki-button variant="ghost" for actions on
the current page. Write link text that identifies its destination when read
on its own.
Read the
<p>Read the <ki-link href="#api-reference">API reference</ki-link>, or browse <ki-link href="https://github.com/kimen-dev/kimen" external>the source on GitHub</ki-link>.</p>Standalone links
In a navigation row or footer, use underline="hover" when placement already
identifies the link. The underline also appears on keyboard focus and on
devices without hover. Use variant="neutral" to match the body ink.
<ki-link href="#api-reference" variant="neutral" underline="hover">API reference</ki-link>External destinations
external requests a new tab with noopener and adds an icon and a spoken
announcement. Override external-label to localize the announcement.
download, target, and rel follow native anchor behavior, with
external taking precedence over target.
API reference
When to use: navigate to a page, section, or resource. Use a descriptive label and keep the default underline in running text. Leave the action binding unset for native navigation.
When not to use: perform an action on the current page. Use ki-button variant="ghost" for that.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
download | download | string | undefined | – | Native download attribute. Set it to an empty string to let the browser choose the file name, or supply a suggested file name. |
external | external | boolean | false | Requests a new tab with noopener and adds an icon and an accessible announcement. An explicit download still follows native download rules. |
external-label | externalLabel | string | '(opens in a new tab)' | Localizable text appended to the accessible name in external mode. |
href | href | string | – | Destination URL. Relative URLs and fragments use native anchor resolution. |
rel | rel | string | undefined | – | Space-separated native link relationships. External links always include noopener. |
target | target | string | undefined | – | Native browsing-context name. External links use _blank. |
underline | underline | "always" | "hover" | 'always' | Keep the underline in running text. Use hover for standalone navigation, where placement identifies the link and keyboard focus still underlines it. |
variant | variant | "neutral" | "primary" | 'primary' | Ink role. Primary uses accent ink and neutral uses body ink. |
Slots
| Slot | Description |
|---|---|
| (default) | Descriptive link text. Use phrasing content without nested interactive controls. |
CSS parts
| Part | Description |
|---|---|
link | The native anchor that renders the link and receives focus. |
CSS custom properties
The public styling contract of ki-link: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-focus-ring-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-link-bg | Transparent backing for primary link text. |
--ki-link-bg-image | Optional image overlay for link backing. |
--ki-link-fg | Accent ink for primary links. |
--ki-link-font-family | Body typeface used by link text. |
--ki-link-icon-gap | Space between the label and the external link icon. |
--ki-link-icon-size | External link icon edge relative to the inherited text size. |
--ki-link-neutral-bg | Transparent backing for neutral link text. |
--ki-link-neutral-fg | Body ink for neutral links. |
--ki-link-radius | Corner radius used by the link focus outline. |
--ki-link-underline-offset | Space between link text and its underline. |
--ki-link-underline-thickness | Resting underline thickness. |
--ki-link-underline-thickness-hover | Underline thickness under a hover-capable pointer. |
--ki-typography-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |