# Elements: Feedback and status

> Plainkit 0.28.0. Generated by scripts/build-skills.mjs from core/dist/elements/api.json. Do not edit: change the source and run the generator.

How to read these tables: see `elements-index.md`. Each element shows its first example; the others are in `references/full/examples-feedback.md` (kept apart so the group files stay short).

## `pk-alert`

**Alert** (Feedback & status). A persistent message in a kind (info, success, warning, danger): optional heading, actions, a dismiss button, a full-bleed banner variant for the top of a page, and a plain form (coloured text only, optionally inline and compact).

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `kind` | enum | `"info"` | `info` `success` `warning` `danger` | The kind setting |
| `heading` | string | `""` |  | The heading setting |
| `dismissible` | boolean | `false` |  | The dismissible setting |
| `banner` | boolean | `false` |  | Page-level strip. |
| `plain` | boolean | `false` |  | Coloured text with no box, icon or panel: the quiet form for a message beside a field or under a button. |
| `subtle` | boolean | `false` |  | A coloured left border and a faint tint background, no icon or dismiss control: a block-level 'finding' treatment between plain text and a full boxed panel, for a reconciliation notice, a nav strip, or a flagged table row. |
| `inline` | boolean | `false` |  | Flows in a line of text (like a span) instead of a block; use with plain. |
| `compact` | boolean | `false` |  | Smaller text and no margin, for an actions strip. |

**Slots**

| Slot | Description |
|---|---|
| (default) | Message. |
| `action` | Buttons or links. |
| `icon` | Custom icon. |

**Events**

| Event | Detail | Description |
|---|---|---|
| `pk-dismiss` | `none` | Dismissed; cancelable. |

**Methods**

| Method | Description |
|---|---|
| `dismiss()` | Dismisses it |

**CSS parts**

| Part | Description |
|---|---|
| `icon` | Kind icon |
| `content` | Title and message |
| `title` | Heading text |
| `message` | Message text |
| `actions` | Action buttons |
| `close` | Close or dismiss button |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-alert-c` | `--color-accent` | Kind colour |

**Accessibility.** role=alert for warning and danger, role=status for info and success, applied to the host; the dismiss button is labelled; colour is never the only signal (icon and heading).

Example: Kinds

```html
<div class="stack"><pk-alert kind="info" heading="Heads up">Imports run overnight.</pk-alert><pk-alert kind="success">Product published.</pk-alert><pk-alert kind="warning" heading="Low stock">Three copies left.</pk-alert><pk-alert kind="danger" heading="Sync failed" dismissible>The channel rejected the update.<pk-button slot="action" variant="ghost" size="mini">Retry</pk-button></pk-alert></div>
```

## `pk-empty-state`

**Empty state** (Feedback). What a list shows when it has no rows: an optional icon, a title, a description and the actions that fill it. Densities for a whole page, a panel or a table row.

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `heading` | string | `""` |  | The title. |
| `level` | number | `3` |  | Heading level exposed to assistive technology. |
| `description` | string | `""` |  | The explanation. |
| `tone` | enum | `"default"` | `default` `compact` `boxed` `error` | Density and frame. |
| `announce` | boolean | `false` |  | Announce the element politely when it appears (role status), for results that replace a search. |

**Slots**

| Slot | Description |
|---|---|
| `icon` | An illustration or icon. |
| `heading` | A rich title; overrides heading. |
| (default) | A rich description; overrides description. |
| `actions` | The next step: a link back or a primary button, centred under the description. |

**CSS parts**

| Part | Description |
|---|---|
| `root` | The wrapper. |
| `icon` | The icon wrapper. |
| `heading` | The title. |
| `description` | The description. |
| `text` | The description prop text; hidden when the default slot has content. |
| `actions` | The action row. |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-empty-state-padding` | `var(--space-8) var(--space-6)` | Padding. |

**Accessibility.** Plain text with a heading whose level you choose. Actions are real buttons and links. Set announce when it replaces content after a search or filter so the change is announced politely.

Example: With an action

```html
<pk-empty-state heading="No products yet" description="Create your first product to see it here.">
  <pk-button slot="actions">Add product</pk-button>
</pk-empty-state>
```

## `pk-hint`

**Hint** (Feedback). An inline explanation that opens in the flow of the page: no tooltip, no hover-only content.

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `label` | string | `"What's this?"` |  | The toggle text. |
| `open` | boolean | `false` |  | Expanded. |
| `tone` | enum | `"info"` | `info` `warn` | Accent colour. |

**Slots**

| Slot | Description |
|---|---|
| (default) | The explanation. |

**Events**

| Event | Detail | Description |
|---|---|---|
| `pk-toggle` | `{ open: bool }` | The hint opened or closed. |

**CSS parts**

| Part | Description |
|---|---|
| `toggle` | The button. |
| `icon` | The i mark. |
| `panel` | The explanation. |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-hint-color` | `var(--color-accent)` | Icon and panel edge colour. |

**Accessibility.** A real button with aria-expanded and aria-controls; the panel is a note region. It works by touch and keyboard, unlike a hover tooltip, and the panel never clips.

Example: Landed cost

```html
<pk-hint label="What is landed cost?">Freight and duties added to the item cost.</pk-hint>
```

## `pk-loading-overlay`

**Loading overlay** (Feedback & status). Covers a region (or the whole viewport with fullscreen) with a spinner and a label while busy, and makes what it covers inert so it cannot be clicked or tabbed into. With delay and min-time it owns the one busy timing rule (pk-page and Blazor's PageBase use it); both default to 0.

**Props**

| Attribute | Type | Default | Description |
|---|---|---|---|
| `busy` | boolean | `false` | Show the overlay and make the content inert (after delay, for at least min-time). aria-busy follows it at once. |
| `label` | string | `""` | Announced and shown. |
| `delay` | number | `0` | Milliseconds busy must last before the overlay appears, so a fast action never flashes it (about 150 for a page). 0 shows it at once. |
| `min-time` (property `minTime`) | number | `0` | Milliseconds the overlay stays once shown, so it never flickers (about 300 for a page). 0 hides it as soon as busy ends. |
| `fullscreen` | boolean | `false` | Cover the viewport. |
| `fill` | boolean | `false` | Fill a definite-height flex column and pass that height to the covered content (a pk-list-page keeps its pinned header and pager). The parent needs a definite height: a flex column, or a block such as the <main> of a pk-app-shell[contain] body (the overlay is capped to it). Without contain it must be the body's direct child. |

**Slots**

| Slot | Description |
|---|---|
| (default) | The content being covered. |

**CSS parts**

| Part | Description |
|---|---|
| `content` | Title and message |
| `overlay` | The covering layer |
| `panel` | The solid chip holding the spinner and label |
| `spinner` | The spinner |
| `label` | Label text |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-fill-shrink` | `0` | Set to 1 on slotted content with fill so it may shrink to the overlay height (page types do). |

**Accessibility.** The overlay is a polite status region announcing the label; the covered content is inert and aria-busy while busy.

Example: Busy region

```html
<pk-loading-overlay busy label="Loading orders…"><pk-card><p>Order list goes here.</p><p class="muted">It is covered and inert while busy.</p></pk-card></pk-loading-overlay>
```

## `pk-progress`

**Progress** (Feedback). A determinate or indeterminate progress bar on the native progress element, with sizes, colours, stripes, a label, a value readout and automatic warning colours.

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `value` | number | `0` |  | Current value. |
| `max` | number | `100` |  | Upper bound. |
| `variant` | enum | `"accent"` | `accent` `ok` `warn` `danger` | Colour. |
| `size` | enum | `"md"` | `md` `sm` `lg` | Height. |
| `striped` | boolean | `false` |  | Diagonal stripes. |
| `indeterminate` | boolean | `false` |  | Unknown duration: the bar sweeps. |
| `label` | string | `""` |  | Text above the bar; also its accessible name. |
| `show-value` (property `showValue`) | boolean | `false` |  | Append the percentage next to the label. |
| `inline` | boolean | `false` |  | Puts the label before the bar and the value after it on one line, instead of a row above the bar. |
| `level-thresholds` (property `levelThresholds`) | string | `""` |  | Two percentages, for example "70,90": the bar turns warn then danger. |

**CSS parts**

| Part | Description |
|---|---|
| `row` | Label and value row. |
| `label` | The label. |
| `value` | The percentage readout. |
| `bar` | The native progress element. |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-progress-color` | `var(--color-accent)` | Fill colour. |
| `--pk-progress-height` | `var(--space-2)` | Bar height. |
| `--pk-progress-track` | `var(--chart-track)` | Track colour. |

**Accessibility.** Built on the native progress element, so its role, value and range are exposed without extra ARIA; the label names it (aria-labelledby). Always give it a label. Indeterminate when no value applies.

Example: Labelled

```html
<pk-progress label="Import" value="60" show-value></pk-progress>
```

## `pk-skeleton`

**Skeleton** (Feedback). A placeholder shape (line, paragraph, circle, block) that holds the layout while content loads.

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `variant` | enum | `"line"` | `line` `text` `circle` `block` | Shape. |
| `lines` | number | `3` |  | Lines in the text variant. |
| `size` | string | `""` |  | Diameter of a circle or height of a block, any CSS length. |
| `label` | string | `"Loading"` |  | Text for assistive technology. |

**CSS parts**

| Part | Description |
|---|---|
| `label` | The visually hidden status text. |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-skeleton-bg` | `var(--color-border)` | Fill colour. |
| `--pk-skeleton-lines` | `3` | Lines in the text variant (set from lines). |
| `--pk-skeleton-size` |  | Circle diameter or block height (set from size). |

**Accessibility.** Decorative. Wrap a loading region in aria-busy="true" and let one skeleton carry the label so a single status is announced. The pulse stops under prefers-reduced-motion.

Example: Paragraph and avatar

```html
<pk-skeleton variant="text" lines="3"></pk-skeleton>
<pk-skeleton variant="circle"></pk-skeleton>
```

## `pk-spinner`

**Spinner** (Feedback). A busy indicator: a ring, three dots or an indeterminate bar, in three sizes, with an overlay mode for a loading panel.

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `variant` | enum | `"ring"` | `ring` `dots` `bar` | Shape. |
| `size` | enum | `"md"` | `md` `sm` `lg` | Size. |
| `label` | string | `"Loading"` |  | Accessible status text. |
| `overlay` | boolean | `false` |  | Dim and cover a position: relative parent. |
| `show-label` (property `showLabel`) | boolean | `false` |  | Shows the label as visible text beside the spinner (under it with overlay), for a loading state that should say what it waits for; without it the label is for screen readers only. |

**CSS parts**

| Part | Description |
|---|---|
| `ring` | The ring. |
| `dots` | The three dots. |
| `bar` | The indeterminate bar. |
| `label` | The visually hidden status text. |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-spinner-size` | `var(--space-5)` | Diameter. |
| `--pk-spinner-color` | `var(--color-accent)` | The moving part. |
| `--pk-spinner-width` | `2px` | Ring thickness. |

**Accessibility.** The host is role=status with a text label read by screen readers. Motion stops under prefers-reduced-motion.

Example: Sizes

```html
<pk-spinner size="sm"></pk-spinner>
<pk-spinner></pk-spinner>
<pk-spinner size="lg"></pk-spinner>
```

## `pk-toast`

**Toast** (Feedback & status). One transient message: kind, optional title, message, an action slot and a dismiss button; pauses its timer on hover and focus.

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `kind` | enum | `"info"` | `info` `success` `warning` `danger` | The kind setting |
| `heading` | string | `""` |  | The heading setting |
| `message` | string | `""` |  | Used when nothing is slotted. |
| `duration` | number | `-1` |  | Milliseconds before it dismisses itself; 0 keeps it until dismissed; -1 is automatic (5s, 8s with an action). |
| `no-close` (property `noClose`) | boolean | `false` |  | Hide the dismiss button. |

**Slots**

| Slot | Description |
|---|---|
| (default) | Message. |
| `action` | One or two buttons. |

**Events**

| Event | Detail | Description |
|---|---|---|
| `pk-dismiss` | `{ reason: string }` | timeout, close, action or method. |

**Methods**

| Method | Description |
|---|---|
| `dismiss()` | Dismisses it |

**CSS parts**

| Part | Description |
|---|---|
| `icon` | Kind icon |
| `content` | Title and message |
| `title` | Heading text |
| `message` | Message text |
| `actions` | Action buttons |
| `close` | Close or dismiss button |

**CSS custom properties**

| Property | Default | Description |
|---|---|---|
| `--pk-toast-c` | `--color-accent` | Kind colour |

**Accessibility.** role=status for info and success, role=alert for warning and danger; the timer pauses on hover and focus; a toast with an action lasts 8s by default.

Example: Kinds

```html
<div class="stack"><pk-toast kind="info" heading="Heads up">Import started.</pk-toast><pk-toast kind="success">Draft saved.<pk-button slot="action" variant="ghost" size="mini">Undo</pk-button></pk-toast><pk-toast kind="warning" heading="Low stock">Three left.</pk-toast><pk-toast kind="danger" heading="Failed">Sync error.</pk-toast></div>
```

## `pk-toast-stack`

**Toast stack** (Feedback & status). Also known as: toast. The live region that holds toasts at one screen position, shows at most three at once and queues the rest; PkToast.show(message, options) creates one per position on demand.

**Props**

| Attribute | Type | Default | Values | Description |
|---|---|---|---|---|
| `position` | enum | `"bottom-end"` | `top-start` `top` `top-end` `bottom-start` `bottom` `bottom-end` | The position setting |
| `max` | number | `3` |  | Visible at once; the rest queue. |

**Slots**

| Slot | Description |
|---|---|
| (default) | pk-toast children. |

**Methods**

| Method | Description |
|---|---|
| `push(toast)` | See the description |

**Writes to host nodes**

| Target | Writes | Why |
|---|---|---|
| the pk-toast children | `hidden` | Toasts past max are hidden until an earlier one is dismissed, and the visible ones are started (their timer). Kept when the element disconnects. |

**Accessibility.** A labelled region; each toast announces itself with its own role.

Example: Stack at a position

```html
<pk-toast-stack position="bottom-end"><pk-toast kind="success">Saved.</pk-toast></pk-toast-stack>
```