# Components

> Components are the shared building blocks behind Kesko’s digital products. Combined, they create consistent, accessible experiences across every Kesko brand.

> Warning: Components are in active development and not yet ready for production use. APIs documented may change without notice.

## Available components (6)

- [Button](/components/button/) (draft) — Button component for interface actions. Renders as a regular link when href is provided. Buttons should primarily be used to trigger events or actions.
- [Divider](/components/divider/) (draft) — Divider component is used to visually separate and group elements horizontally or vertically.
- [Icon](/components/icon/) (stable) — Icons are symbols that can be used to provide meaning in addition to text labels. Clear and consistent icon usage could help people complete their tasks.
- [Spinner](/components/spinner/) (draft) — Spinner component is an animated icon that lets users know content or result of an action is being loaded.
- [Stack](/components/stack/) (draft) — Stack component manages the vertical or horizontal layout of direct children using flexbox and adjustable spacing.
- [Visually hidden](/components/visually-hidden/) (draft) — Visually hidden component hides content visually while retaining readability by screen readers for accessibility.


## Component APIs

### Button (draft)

- Import: `import { Button } from "@kesko/components";`
- HTML class: `.k-button`

Button component for interface actions. Renders as a regular link when href is provided. Buttons should primarily be used to trigger events or actions.

#### Props
- `variant` — `"default" | "primary" | "secondary" | "plain" | "text" | "inverted"` (default: `"default"`) The style variant of the button.
- `size` — `"sm" | "md" | "lg"` (default: `"md"`) The size of the button.
- `expand` — `boolean` (default: `false`) Makes the button fit its container.
- `transparent` — `boolean` (default: `false`) Removes the background from the default and plain variants.
- `disabled` — `boolean` (default: `false`) Disables the component. Native `disabled` on buttons, `aria-disabled` on links.
- `loading` — `boolean` (default: `false`) Shows loading state with spinner.
- `iconOnly` — `boolean` (default: `false`) Renders the button as a square with no horizontal padding for a single icon child. Pair with `aria-label` for accessibility.
- `aria-label` — `string` Accessible name. Required for `iconOnly` buttons that have no visible text.
- `aria-labelledby` — `string` `id` of an element that labels this button. Use instead of `aria-label` when the label is already visible elsewhere on the page.
- `aria-describedby` — `string` `id` of an element that describes this button (typically helper text).
- `aria-controls` — `string` `id` of the element(s) controlled by this button.
- `aria-expanded` — `boolean | "true" | "false"` Whether a grouping controlled by this button is expanded.
- `aria-haspopup` — `boolean | "menu" | "listbox" | "tree" | "grid" | "dialog" | "true" | "false"` Availability and type of popup this button opens.
- `href` — `string` Renders as an anchor element.
- `target` — `"_self" | "_blank" | "_parent" | "_top"` Where to open the linked URL.
- `download` — `boolean | string` Triggers a file download. Pass `true` to use the server filename or a string to override it.

#### Events
- `onClick` — `(event: MouseEvent<ButtonTarget>) => void` Handler called on click (mouse, touch, or keyboard activation).
- `onFocus` — `(event: FocusEvent<ButtonTarget>) => void` Handler called when the element receives focus.
- `onBlur` — `(event: FocusEvent<ButtonTarget>) => void` Handler called when the element loses focus.

#### CSS custom properties
- `--k-button-bg` (default: `var(--k-color-bg)`) Overrides the background color.
- `--k-button-text` (default: `var(--k-color-text-link)`) Overrides the text color.
- `--k-button-border` (default: `var(--k-color-text-link)`) Overrides the border color.
- `--k-button-radius` (default: `var(--k-radius-button)`) Overrides the border radius.
- `--k-button-focus` (default: `var(--k-color-border-focus)`) Overrides the focus ring color.
- `--k-button-bg-hover` (default: `var(--k-button-bg)`) Overrides the hover background color.
- `--k-button-bg-active` (default: `var(--k-button-bg)`) Overrides the pressed background color.
- `--k-button-text-hover` Overrides the hover text color.
- `--k-button-text-active` Overrides the pressed text color.
- `--k-button-ring-hover` Overrides the grow-ring color on hover.
- `--k-button-ring-active` Overrides the grow-ring color when pressed.
- `--k-button-height` Overrides the button height at the active size.

### Divider (draft)

- Import: `import { Divider } from "@kesko/components";`
- HTML class: `.k-divider`

Divider component is used to visually separate and group elements horizontally or vertically.

#### Props
- `orientation` — `"horizontal" | "vertical"` (default: `"horizontal"`) The orientation of the divider.

#### CSS custom properties
- `--k-divider-color` (default: `var(--k-color-border-divider)`) Overrides the divider color.
- `--k-divider-size` (default: `1px`) Overrides the divider size.

### Icon (stable)

- Import: `import { Icon } from "@kesko/components";`
- HTML class: `.k-icon`

Icons are symbols that can be used to provide meaning in addition to text labels. Clear and consistent icon usage could help people complete their tasks.

#### Props
- `color` — `string` (default: `currentColor`) Any CSS color value or a [design token](/tokens/). When omitted, inherits current text color via CSS cascade.
- `label` — `string` Sets `aria-label` and `role="img"` to the icon. Omit for decorative icons (`aria-hidden` set by default).
- `size` — `"xs" | "sm" | "md" | "lg" | "xl" | number | string` (default: `"md"`) Size of the icon. Please see [size tokens](/tokens/#sizes) for more details.

### Spinner (draft)

- Import: `import { Spinner } from "@kesko/components";`
- HTML class: `.k-spinner`

Spinner component is an animated icon that lets users know content or result of an action is being loaded.

#### Props
- `size` — `"sm" | "md" | "lg" | "xl" | "2xl"` (default: `"md"`) The size of the spinner.
- `label` — `string` (default: `"Loading"`) Accessible label for the spinner. Defaults to "Loading".

#### CSS custom properties
- `--k-spinner-color` (default: `currentColor`) Overrides the spinner color.
- `--k-spinner-size` (default: `var(--k-size-component-spinner)`) Overrides the spinner size.

### Stack (draft)

- Import: `import { Stack } from "@kesko/components";`
- HTML class: `.k-stack`

Stack component manages the vertical or horizontal layout of direct children using flexbox and adjustable spacing.

#### Props
- `direction` — `"column" | "row"` (default: `"column"`) Layout direction. Defaults to "column".
- `gap` — `"3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"` (default: `"md"`) Gap between children, mapped to the `--k-space- ` scale. Defaults to "md".
- `align` — `"start" | "center" | "end" | "stretch"` (default: `"start"`) Cross-axis alignment. Defaults to "start".
- `wrap` — `boolean` (default: `false`) Allow items to wrap to a new line when they overflow the container.

#### CSS custom properties
- `--k-stack-gap` (default: `var(--k-space-md)`) Overrides the gap between children.

### Visually hidden (draft)

- Import: `import { VisuallyHidden } from "@kesko/components";`
- HTML class: `.k-visually-hidden`

Visually hidden component hides content visually while retaining readability by screen readers for accessibility.