# Oyna UI: the whole documentation

> A Vue 3 component library with a dark glass look. Plain CSS, no Tailwind.

# Why Oyna UI

I was building [invoke.wtf](https://invoke.wtf), a trainer for Invoker from Dota 2, and wanted a UI kit that looked the way I had in mind: dark glass over a rich background, no grey borders, light instead of lines, big condensed numbers, everything reachable from the keyboard.

I did not find one. Most Vue UI kits look like admin panels: white cards, grey borders, the same blue button. So I drew the interface by hand.

Oyna UI is that look taken out of the project and made into a library: the same surfaces, rings, type and hotkeys, without anything about the game. I made it for myself. If it suits your project, use it too.

## What is inside

Plain CSS and Vue. There is no Tailwind, no UnoCSS and no CSS-in-JS: you import one stylesheet and use the components, with nothing to configure. I did not want a library that makes you adopt a styling tool to get a button.

The one dependency is [Reka UI](https://reka-ui.com). Focus traps, keyboard navigation and screen reader support are hard to get right, and it already gets them right, so accessibility is not reinvented here. Everything you see is Oyna UI; Reka UI works underneath, where there is nothing to look at.

## What it is for

Interfaces that want character: dashboards, tools, landing pages, side projects. It is one look, done on purpose, not a neutral base to build any design on. You can change the accent, the radius and the fonts; you cannot make it look like a white admin panel, and it has no light theme.

## Where to see it

- [invoke.wtf](https://invoke.wtf) is where the look was born. The site itself is written by hand: the library came out of it, not the other way round.
- The [dashboard](https://oyna-ui.org/examples/dashboard) and [settings](https://oyna-ui.org/examples/settings) examples are built only from the library's components.

## The name

_Oyna_ is Uzbek for "glass", and also for "window" and "mirror".

Source: https://oyna-ui.org/guide/why

---

# Installation

## Install

```bash [npm]
npm install oyna-ui
```

```bash [pnpm]
pnpm add oyna-ui
```

```bash [yarn]
yarn add oyna-ui
```

```bash [bun]
bun add oyna-ui
```

`vue` 3.5 or newer is a peer dependency.

## Register

Import the stylesheet once and register the components:

```ts
import oyna from 'oyna-ui'
import { createApp } from 'vue'
import App from './App.vue'
import 'oyna-ui/style.css'

createApp(App).use(oyna).mount('#app')
```

Or import only what you use; the rest is left out of your bundle:

```vue
<script setup lang="ts">
import { OButton, OCard } from 'oyna-ui'
</script>
```

The stylesheet is plain CSS. You need neither Tailwind nor UnoCSS.

## Fonts

The look relies on two typefaces: a condensed display face for numbers and headings, and a plain sans for text. The library does not bundle font files, so loading them is one more line. Pick one of three ways.

**From Google Fonts, in one import.** The quickest:

```ts
import 'oyna-ui/style.css'
import 'oyna-ui/fonts.css'
```

The files come from Google's servers. If that is a problem for you — privacy rules, an offline app — use the next way.

**Served by you, with Fontsource.** The fonts become part of your own build:

```bash [npm]
npm install @fontsource/noto-sans @fontsource/barlow-condensed @fontsource/fira-sans-condensed
```

```bash [pnpm]
pnpm add @fontsource/noto-sans @fontsource/barlow-condensed @fontsource/fira-sans-condensed
```

```bash [yarn]
yarn add @fontsource/noto-sans @fontsource/barlow-condensed @fontsource/fira-sans-condensed
```

```bash [bun]
bun add @fontsource/noto-sans @fontsource/barlow-condensed @fontsource/fira-sans-condensed
```

```ts
import '@fontsource/noto-sans/400.css'
import '@fontsource/noto-sans/600.css'
import '@fontsource/noto-sans/700.css'
import '@fontsource/barlow-condensed/700.css'
import '@fontsource/barlow-condensed/800.css'
// only if your interface has Cyrillic text
import '@fontsource/fira-sans-condensed/700.css'
import '@fontsource/fira-sans-condensed/800.css'
```

**Your own typefaces.** Set `--o-font-sans` and `--o-font-display` to whatever you already load; see [Theming](https://oyna-ui.org/guide/theming.md).

| Family              | Weights       | Used for                      |
| ------------------- | ------------- | ----------------------------- |
| Noto Sans           | 400, 600, 700 | text                          |
| Barlow Condensed    | 700, 800      | numbers and headings          |
| Fira Sans Condensed | 700, 800      | Cyrillic numbers and headings |

Load every weight listed: a missing weight is synthesized by the browser and looks lighter.

### Without the fonts

Nothing breaks. Text falls back to the system's own sans, and headings to a condensed face the system has: Avenir Next Condensed on macOS and iOS, Arial Narrow on Windows, Roboto Condensed on Android. It is recognisably the same look, a little less sharp. The same fallbacks show for a moment while the real fonts are on their way.

## Background

The glass needs something behind it. Put [`OBackground`](https://oyna-ui.org/components/background.md) at the top of your app:

```vue
<template>
  <OBackground />
  <RouterView />
</template>
```

## Dependencies

Tabs, Dialog, Select, DropdownMenu, Popover, Tooltip and PinInput are built on [Reka UI](https://reka-ui.com), which handles focus and accessibility. It is installed with the library; you don't set it up.

## What the stylesheet does to the page

Besides the components, `style.css` sets on `body` a zero margin, the text font, white text and the
dark background colour, and makes scrollbars thin and translucent. Nothing else is reset.

## With an AI assistant

An assistant has not seen this library while it was trained, so point it at the docs written for it:

- [`/llms.txt`](https://oyna-ui.org/llms.txt) — what the library is, the rules that are easy to get wrong, and a list of every page;
- [`/llms-full.txt`](https://oyna-ui.org/llms-full.txt) — the whole documentation in one file;
- every page of this site also exists as plain Markdown: add `.md` to its address, as in `/components/button.md`.

Paste the first address into the chat, or add a line to your project's instructions for the assistant: "This project uses Oyna UI; read https://oyna-ui.org/llms.txt before writing interface code."

Source: https://oyna-ui.org/guide/installation

---

# Theming

Every colour, radius and font is a CSS variable. Override them on `:root`, or on any element to restyle one part of the page.

```css
:root {
  --o-accent: #4dd2ff;
  --o-radius: 10px;
}
```

```vue
<div style="--o-accent: #4dd2ff">
  <OButton variant="primary">Primary</OButton>
  <OButton variant="soft">Soft</OButton>
  <OCard signal="accent">A card with another accent</OCard>
</div>
```

## Tokens

| Variable                                       | Default                                                             | Meaning                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `--o-accent`                                   | `#a5ff4d`                                                           | The one bright colour: the main thing on the screen              |
| `--o-danger`                                   | `#ff8a8a`                                                           | Something at stake                                               |
| `--o-on-accent`                                | `#111`                                                              | Text on an accent fill                                           |
| `--o-surface`                                  | `rgb(0 0 0 / 0.3)`                                                  | Glass                                                            |
| `--o-surface-strong`                           | `rgb(0 0 0 / 0.4)`                                                  | Darker glass, for text-heavy content                             |
| `--o-layer`                                    | `rgb(20 20 26 / 0.8)`                                               | What floats over the page: dialog, popover, menu, tooltip, toast |
| `--o-layer-blur`                               | `16px`                                                              | How much the page is blurred under a layer; `0px` turns it off   |
| `--o-fill-1` … `--o-fill-4`                    | white at 4, 8, 12, 22 %                                             | Stripes, controls, hover, bars                                   |
| `--o-text`, `--o-text-2`, `--o-text-3`         | white at 100, 75, 50 %                                              | Text                                                             |
| `--o-radius-sm`, `--o-radius`, `--o-radius-lg` | `8px`, `14px`, `24px`                                               | Small controls, cards, dialogs                                   |
| `--o-font-sans`                                | Noto Sans, then the system sans                                     | Text                                                             |
| `--o-font-display`                             | Barlow Condensed, Fira Sans Condensed, then a condensed system face | Numbers and headings                                             |
| `--o-duration`                                 | `160ms`                                                             | Every transition                                                 |
| `--o-bg`, `--o-bg-1` … `--o-bg-4`              |                                                                     | [Background](https://oyna-ui.org/components/background.md)                             |

## With Tailwind or UnoCSS

The library needs neither, but if your project already uses one, the tokens are there as utilities, so the blocks you write yourself match the components. Every name starts with `o-`: nothing of your own theme is replaced. The values are the CSS variables above, so a theme you set with them reaches the utilities without a rebuild.

**Tailwind 4.** One more import after Tailwind's own:

```css
@import 'tailwindcss';
@import 'oyna-ui/tailwind.css';
```

**UnoCSS.** A preset, next to `presetWind3` or `presetWind4`:

```ts
import { defineConfig, presetWind4 } from 'unocss'
import { presetOyna } from 'oyna-ui/unocss'

export default defineConfig({ presets: [presetWind4(), presetOyna()] })
```

Then, in either:

```vue
<div class="rounded-o bg-o-surface p-6 text-o-text-2">
  <h2 class="font-o-display text-o-text">Deploys</h2>
  <p class="text-o-text-3">Nothing yet.</p>
</div>
```

| Utilities                                                  | From                                                  |
| ---------------------------------------------------------- | ----------------------------------------------------- |
| `*-o-accent`, `*-o-danger`, `*-o-on-accent`                | The accent, the danger colour, text on an accent fill |
| `*-o-surface`, `*-o-surface-strong`, `*-o-layer`, `*-o-bg` | Glass, darker glass, what floats, the page            |
| `*-o-fill-1` … `*-o-fill-4`                                | The white fills                                       |
| `*-o-text`, `*-o-text-2`, `*-o-text-3`                     | Text at 100, 75 and 50 %                              |
| `rounded-o-sm`, `rounded-o`, `rounded-o-lg`                | The three radii                                       |
| `font-o-sans`, `font-o-display`                            | The two typefaces                                     |

`*` is any utility that takes a colour: `bg-`, `text-`, `border-`, `ring-`, `fill-`. Tailwind also gets `duration-o` (the library's transition time, zero under reduced motion) and `backdrop-blur-o-layer`.

## Reduced motion

When the user asks for reduced motion, `--o-duration` becomes `0ms` and every transition in the library stops. Use the variable in your own transitions to get the same behaviour.

Source: https://oyna-ui.org/guide/theming

---

# Hotkeys

Hotkeys are read from the physical key (`KeyboardEvent.code`), not from the character it types. `KeyR` is the same key on a QWERTY, an AZERTY and a Russian layout.

A hotkey is ignored:

- while the user types in an `input`, a `textarea`, a `select` or an editable element. A checkbox, a radio and a switch are not typed into, so hotkeys work on them, except Space and the arrow keys, which are their own;
- with Ctrl, Cmd or Alt held, so browser shortcuts keep working;
- on key repeat, when the key is held down;
- for `Enter` and `Space`, when a button or a link has focus: that element handles the key itself.

The numpad Enter counts as `Enter`.

While a [dialog](https://oyna-ui.org/components/dialog.md) or a [popover](https://oyna-ui.org/components/popover.md) is open, only the hotkeys set up inside it work. While a [select](https://oyna-ui.org/components/select.md) or a [dropdown menu](https://oyna-ui.org/components/dropdown-menu.md) is open, or a [key capture](https://oyna-ui.org/components/key-capture.md) waits for a key, none do.

## On a button

The simplest way: [`OButton`](https://oyna-ui.org/components/button.md) and [`OToggle`](https://oyna-ui.org/components/toggle.md) take a `hotkey`, show it and react to it.

```vue
<OButton variant="soft" hotkey="KeyR" @click="retry">
  Retry
</OButton>
```

## useHotkey

For anything that is not a button. The listener lives as long as the component.

```vue
<script setup lang="ts">
import { useHotkey } from 'oyna-ui'
import { ref } from 'vue'

const muted = ref(false)
const open = ref(true)

useHotkey('KeyM', () => (muted.value = !muted.value))
// the key can be reactive, and the hotkey can be switched off
useHotkey('Escape', () => (open.value = false), { enabled: () => open.value })
</script>
```

| Argument          | Type                                    | Description                                              |
| ----------------- | --------------------------------------- | -------------------------------------------------------- |
| `code`            | `MaybeRefOrGetter<string \| undefined>` | Physical key, e.g. `KeyR`, `Digit1`, `Enter`, `Escape`   |
| `handler`         | `(event: KeyboardEvent) => void`        | Called on the key press; the default action is prevented |
| `options.enabled` | `MaybeRefOrGetter<boolean>`             | `false` switches the hotkey off                          |

## hotkeyLabel

`hotkeyLabel(code)` returns what to print for a key: `KeyR` → `R`, `Digit1` → `1`, `Escape` → `Esc`, `ArrowUp` → `↑`, `Slash` → `/`.

The label names the key's position on a QWERTY keyboard. On another layout the same key may carry another letter; pass your own text where that matters.

## On a touch screen

A phone has no keys to show. Where the main pointer is a finger (`pointer: coarse`), Button, Toggle
and the dialog's close button hide their key; the hotkey itself stays registered, so a tablet with a
keyboard attached still reacts to it.

The same media query makes the library easier to hit: small buttons, the crosses of Alert and Tag,
checkboxes, radios and switches get a target of about 44px without changing their shape, segmented
tabs grow taller, and fields use 16px text, so iOS does not zoom the page on focus.

Source: https://oyna-ui.org/guide/hotkeys

---

# Icons

Oyna UI ships no icons. Put any SVG in a component's slot and it takes the size of the text next to it. The examples on this site use [Lucide](https://lucide.dev): restrained line icons that match the look.

```bash [npm]
npm install @lucide/vue
```

```bash [pnpm]
pnpm add @lucide/vue
```

```bash [yarn]
yarn add @lucide/vue
```

```bash [bun]
bun add @lucide/vue
```

```vue
<script setup lang="ts">
import { ArrowRight, Check, Rocket, Settings } from '@lucide/vue'
</script>

<template>
  <OButton variant="primary"><Rocket /> Deploy</OButton>
  <OButton>Continue <ArrowRight /></OButton>
  <OButton icon shape="pill" aria-label="Settings"><Settings /></OButton>
  <OBadge tone="accent"><Check /> Passed</OBadge>
</template>
```

## Where icons are sized for you

| Component                                                                              | How                                                |
| -------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [Button](https://oyna-ui.org/components/button.md), [Toggle](https://oyna-ui.org/components/toggle.md), [Badge](https://oyna-ui.org/components/badge.md) | An `<svg>` in the slot                             |
| [DropdownMenu](https://oyna-ui.org/components/dropdown-menu.md)                                              | `icon` of an item: the component itself, not a tag |
| [Empty](https://oyna-ui.org/components/empty.md)                                                             | The `icon` slot                                    |

Anywhere else an icon is just an element in your own layout.

## Rules of the look

- **Line icons, not filled ones, and no emoji.** They take the colour of the text, so they follow the tone of the component.
- **An icon alone needs a name.** Give an icon-only button an `aria-label`; a [tooltip](https://oyna-ui.org/components/tooltip.md) on top helps sighted users.
- **An icon next to a word is decoration.** Lucide marks its icons `aria-hidden` already, so screen readers read only the word.

```vue
<OTooltip text="Help">
  <OButton icon shape="pill" aria-label="Help"><CircleHelp /></OButton>
</OTooltip>
```

## Other icon sets

Anything that renders an `<svg>` works the same way: another icon package, or an SVG you paste in. Icon fonts and CSS-mask icons (such as UnoCSS `i-*` classes) are not sized by the components; set their size yourself.

Source: https://oyna-ui.org/guide/icons

---

# Background

The stage behind the glass: colour glows, a vignette that keeps the centre readable, and noise. Generated in CSS, with no image files.

You are looking at it: this site uses the default background.

```vue
<template>
  <OBackground />
  <main>…</main>
</template>
```

It is fixed to the viewport and sits behind the page (`z-index: -1`), so place it anywhere in your app.

## Colours

Four glows over a base colour, each a CSS variable:

```css
:root {
  --o-bg: #0b0b0f;
  --o-bg-1: #3a4fd0; /* top left */
  --o-bg-2: #8a2bb8; /* top right */
  --o-bg-3: #0e7f78; /* bottom right */
  --o-bg-4: #b0561a; /* bottom left */
}
```

## Your own background

`OBackground` is optional. Any rich background works — a photo, a video, a gradient of your own — as long as it is dark enough for white text. Over a very busy one, use the `strong` [surface](https://oyna-ui.org/components/surface.md).

Source: https://oyna-ui.org/components/background

---

# Surface

Glass: a translucent dark fill over the background. No borders. [`OCard`](https://oyna-ui.org/components/card.md) is a surface with padding, the darker fill, and an optional header and footer.

```vue
<OSurface>
Surface
</OSurface>

<OSurface strong>
Strong surface
</OSurface>

<OCard>
Card
</OCard>
```

`OSurface` has no padding of its own: it is the fill and the radius, for layouts you size yourself.

## Signal

A ring appears only when it means something. `accent` marks the main thing on the screen, or what belongs to the user. `danger` marks something at stake. Never use a ring as decoration: if everything has one, none of them says anything.

```vue
<OCard signal="accent">
Your plan
</OCard>

<OCard signal="danger">
Quota runs out
</OCard>
```

## Props

### OSurface

| Prop     | Type                   | Default | Description                                                  |
| -------- | ---------------------- | ------- | ------------------------------------------------------------ |
| `as`     | `string`               | `'div'` | Element to render                                            |
| `strong` | `boolean`              | `false` | A darker fill, for text-heavy content over a busy background |
| `signal` | `'accent' \| 'danger'` | —       | A ring that means something                                  |

For `OCard`, see [Card](https://oyna-ui.org/components/card.md).

Source: https://oyna-ui.org/components/surface

---

# Card

The block most screens are made of: a darker [surface](https://oyna-ui.org/components/surface.md) with padding, and an optional header and footer.

```vue
<OCard label="Usage" title="Requests">
  <template #actions>
    <OBadge>Pro</OBadge>
  </template>

  <span class="number">131.6k</span>
  <OProgress :value="72" aria-label="Plan usage" />

  <template #footer>72% of the plan, resets on Monday.</template>
</OCard>
```

Everything but the content is optional. A card with no header and no footer is just padding around what you put in it.

## Header

- `label` — a small caption: what the card is about. The quiet way to name a card, and the one to reach for first.
- `title` — a heading in display type, for a card that is a section of the page. It is an `<h3>`; set `title-as` to the level that fits your page.
- `actions` — the slot at the right end: a badge, a button, a menu.

```vue
<OCard label="Endpoints">
  <template #actions>
    <OButton icon size="sm" variant="ghost" aria-label="More"><Ellipsis /></OButton>
  </template>
  Only a label and an action.
</OCard>

<OCard title="Billing" title-as="h2">Only a title.</OCard>
```

## Footer

What comes after the content: a total, a note, a link to more. A thin line sets it apart — a line between two parts of one card, not a border around it.

## Signal

The ring from [Surface](https://oyna-ui.org/components/surface.md#signal): `accent` for the main thing, `danger` for something at stake. One per screen, rarely two.

```vue
<OCard signal="accent" label="Next release">v1.4.1</OCard>
<OCard signal="danger" label="Quota runs out in">3 days</OCard>
```

## Props and slots

| Prop      | Type                   | Default | Description                   |
| --------- | ---------------------- | ------- | ----------------------------- |
| `label`   | `string`               | —       | A small caption over the card |
| `title`   | `string`               | —       | A heading in display type     |
| `titleAs` | `string`               | `'h3'`  | The element of the title      |
| `signal`  | `'accent' \| 'danger'` | —       | A ring that means something   |
| `as`      | `string`               | `'div'` | Element to render             |

| Slot      | Description                     |
| --------- | ------------------------------- |
| default   | The content                     |
| `actions` | At the right end of the header  |
| `footer`  | Under the content, after a line |

Source: https://oyna-ui.org/components/card

---

# Button

An action. One accent button per screen is the main thing; the rest stay quiet. A button can display its hotkey and own it.

```vue
<OButton variant="primary" size="lg" hotkey="Enter" @click="save">
  Save changes
</OButton>

<OButton size="lg" @click="cancel">
  Cancel
</OButton>
```

## Variants

Five levels of weight. Use `primary` once per screen.

```vue
<OButton variant="primary">
Primary
</OButton>

<OButton>
Secondary
</OButton>

<OButton variant="soft">
Soft
</OButton>

<OButton variant="ghost">
Ghost
</OButton>

<OButton variant="link">
Link →
</OButton>
```

## Sizes and shapes

Three sizes, a pill shape for navigation, and an icon-only button. Give an icon-only button an `aria-label`.

```vue
<OButton size="sm">
Small
</OButton>

<OButton>
Medium
</OButton>

<OButton size="lg">
Large
</OButton>

<OButton shape="pill">
Pill
</OButton>

<OButton icon shape="pill" aria-label="Help">
?
</OButton>
```

## Link and current page

With `href` the button renders a link. `aria-current` marks the current page in a navigation, as in the header of this site.

```vue
<OButton shape="pill" href="/guide">
Guide
</OButton>

<OButton shape="pill" href="/components" aria-current="page">
Components
</OButton>
```

## Hotkey

Pass a physical key code: the button shows the key and reacts to it on any keyboard layout. See [Hotkeys](https://oyna-ui.org/guide/hotkeys.md) for when a key is ignored.

```vue
<OButton variant="soft" hotkey="KeyR" @click="retry">
Retry
</OButton>

<OButton hotkey="Escape" @click="close">
Close
</OButton>

<OButton hotkey="KeyS" hotkey-label="S · save">
Custom label
</OButton>
```

## Loading

Work is under way: the button shows a [spinner](https://oyna-ui.org/components/spinner.md), stays lit, and reacts neither to clicks nor to its hotkey.

```vue
<OButton variant="primary" :loading="deploying" hotkey="Enter" @click="deploy">Deploy</OButton>
```

## Icons

An `<svg>` in the slot takes the size of the text. See [Icons](https://oyna-ui.org/guide/icons.md).

## Disabled

A disabled button does not react to its hotkey either.

## Props

| Prop          | Type                                                      | Default       | Description                                                                 |
| ------------- | --------------------------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| `variant`     | `'primary' \| 'secondary' \| 'soft' \| 'ghost' \| 'link'` | `'secondary'` | Visual weight                                                               |
| `size`        | `'sm' \| 'md' \| 'lg'`                                    | `'md'`        |                                                                             |
| `shape`       | `'rounded' \| 'pill'`                                     | `'rounded'`   | Pill for navigation and chips                                               |
| `icon`        | `boolean`                                                 | `false`       | A square (or round, with `pill`) button holding only an icon                |
| `hotkey`      | `string`                                                  | —             | Physical key (`KeyboardEvent.code`) that clicks the button; shown inside it |
| `hotkeyLabel` | `string`                                                  | from `hotkey` | Text shown for the key                                                      |
| `disabled`    | `boolean`                                                 | `false`       | Also turns the hotkey off                                                   |
| `loading`     | `boolean`                                                 | `false`       | Shows a spinner; no clicks, no hotkey                                       |
| `href`        | `string`                                                  | —             | Renders a link instead of a button                                          |
| `type`        | `'button' \| 'submit' \| 'reset'`                         | `'button'`    | Set `submit` inside a form                                                  |

Source: https://oyna-ui.org/components/button

---

# Kbd

A key. It looks like a key cap: a face lit from above, standing on a dark lip.

```vue
<p>Press <OKbd>Esc</OKbd> to close, <OKbd>⌘</OKbd> <OKbd>K</OKbd> to search.</p>

<OKbd variant="cap">Q</OKbd>
<OKbd variant="cap">W</OKbd>
<OKbd variant="cap">E</OKbd>
<OKbd variant="cap">Shift</OKbd>
```

- `key`, the default — a small cap inside a sentence. It is sized by the text around it.
- `cap` — a large cap on its own, in display type: a list of bindings, a tutorial.
- `outline` — a flat key for inside a control, where a cap has no room. It takes the colour of the text around it.

## Lights up when pressed

Give a key its physical `code` and it lights up for as long as that key is held. Try `Q`, `W`, `E` or `Space` right here:

```vue
<OKbd variant="cap" code="KeyQ">Q</OKbd>
<OKbd variant="cap" code="KeyW">W</OKbd>
<OKbd variant="cap" code="KeyE">E</OKbd>
<OKbd variant="cap" code="Space">Space</OKbd>
```

The cap does not sink or move: the library answers with light. The `code` is the key's position on the keyboard (`KeyboardEvent.code`), as for a [hotkey](https://oyna-ui.org/guide/hotkeys.md), so it works on any layout. Without a `code`, a key is just a picture of a key.

This makes a hint under a screen confirm itself: the user presses the key and sees it was the right one.

## In a control

```vue
<OKbd variant="outline">M</OKbd>
```

You rarely need it yourself: a [button](https://oyna-ui.org/components/button.md#hotkey) and a [toggle](https://oyna-ui.org/components/toggle.md) draw the key of their own hotkey.

## Props

| Prop      | Type                          | Default | Description                                                             |
| --------- | ----------------------------- | ------- | ----------------------------------------------------------------------- |
| `variant` | `'key' \| 'cap' \| 'outline'` | `'key'` |                                                                         |
| `code`    | `string`                      | —       | Physical key (`KeyboardEvent.code`); the cap lights up while it is held |

Source: https://oyna-ui.org/components/kbd

---

# Badge

A short label next to something: a plan, a status, a count.

```vue
<OBadge>
Pro
</OBadge>

<OBadge tone="accent">
New
</OBadge>

<OBadge tone="danger">
Expired
</OBadge>
```

Put an [icon](https://oyna-ui.org/guide/icons.md) before the text: the badge sizes it and sets the gap.

For something the user applied and can remove, use a [tag](https://oyna-ui.org/components/tag.md).

## Props

| Prop   | Type                   | Default | Description |
| ------ | ---------------------- | ------- | ----------- |
| `tone` | `'accent' \| 'danger'` | —       |             |

Source: https://oyna-ui.org/components/badge

---

# Tag

Something the user applied and can take off: a filter, a label, a recipient.

```vue
<OTag>production</OTag>
<OTag tone="accent">v1.4.1</OTag>
<OTag tone="danger">failing</OTag>
<OTag><GitBranch /> main</OTag>
<OTag removable>removable</OTag>
```

## Removable

`removable` adds a remove button. It emits `remove`; taking the tag away is up to you. Give the button a name that says what goes: a screen reader hears only the button.

```vue
<OTag
  v-for="filter in filters"
  :key="filter"
  removable
  :remove-label="`Remove the filter ${filter}`"
  @remove="remove(filter)"
>
  {{ filter }}
</OTag>
```

## Tag or badge

They look alike on purpose and differ in one thing: who put it there.

- **Tag** — the user did: a filter, a label. It can usually be removed. Squarer corners.
- **[Badge](https://oyna-ui.org/components/badge.md)** — the system did: a status, a plan, a count. It cannot be removed. A pill.

For a choice that is on or off, use a [toggle](https://oyna-ui.org/components/toggle.md).

## Props

| Prop          | Type                   | Default    | Description                                      |
| ------------- | ---------------------- | ---------- | ------------------------------------------------ |
| `tone`        | `'accent' \| 'danger'` | —          |                                                  |
| `removable`   | `boolean`              | `false`    | Shows a remove button that emits `remove`        |
| `removeLabel` | `string`               | `'Remove'` | The name of the remove button for screen readers |

Source: https://oyna-ui.org/components/tag

---

# Avatar

A person, as a round picture or as initials when there is no picture. For a member in a list, the author of a deploy, the account in a header.

```vue
<OAvatar name="Ada Lovelace" size="sm" />
<OAvatar name="Ada Lovelace" />
<OAvatar name="Ada Lovelace" size="lg" />
<OAvatar name="grace" size="lg" />
```

The initials are the first letters of the first two words of `name`. The name is also what a screen reader says, so give the full one even when a picture is shown.

## With a picture

Pass `src`. The initials show until the picture has loaded, and stay if it fails to load, so a broken address never leaves an empty circle.

```vue
<OAvatar name="Oyna UI" src="/favicon.svg" size="lg" />
<OAvatar name="Missing Picture" src="/no-such-picture.png" size="lg" />
```

## Next to a name

An avatar sits in a row with text; the row is yours to lay out.

```vue
<div style="display: flex; align-items: center; gap: 10px">
  <OAvatar name="Ada Lovelace" />
  <div>
    <b>Ada Lovelace</b>
    <span>ada@example.com</span>
  </div>
</div>
```

## Props

| Prop   | Type                   | Default  | Description                                    |
| ------ | ---------------------- | -------- | ---------------------------------------------- |
| `name` | `string`               | required | Read out by screen readers; gives the initials |
| `src`  | `string`               | —        | Address of the picture                         |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'`   | 24, 32 or 48 px                                |

Built on [Reka UI](https://reka-ui.com) Avatar.

Source: https://oyna-ui.org/components/avatar

---

# Input

A text field. Its edge is a quiet 1px line; the ring turns accent on focus and danger when the value is wrong. `OField` adds a label and a message under it.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
</script>

<template>
  <OInput v-model="name" placeholder="Your name" />
</template>
```

Every attribute goes to the `<input>` itself: `type`, `placeholder`, `maxlength`, `autocomplete`, `disabled`.

## Field

A label, the control, and a hint. When there is an `error`, it replaces the hint and the input gets the danger ring. The label and the message are tied to the input for screen readers; you set no ids.

Try typing something other than `admin`:

```vue
<OField label="Nickname" hint="2–16 characters" :error="error">
  <OInput v-model="nickname" />
</OField>
```

The message keeps its line when empty, so the layout does not jump when an error appears.

## With a button

```vue
<form @submit.prevent="subscribe">
  <OInput v-model="email" type="email" placeholder="Email" aria-label="Email" />
  <OButton variant="primary" type="submit">Subscribe</OButton>
</form>
```

Without an `OField`, give the input an `aria-label`.

## Props

### OInput

| Prop      | Type               | Default | Description                                                       |
| --------- | ------------------ | ------- | ----------------------------------------------------------------- |
| `v-model` | `string \| number` | —       |                                                                   |
| `invalid` | `boolean`          | `false` | A danger ring. Inside an `OField` with an error it is set for you |

### OField

| Prop    | Type     | Default  | Description                                     |
| ------- | -------- | -------- | ----------------------------------------------- |
| `label` | `string` | required |                                                 |
| `hint`  | `string` | —        | Shown under the control                         |
| `error` | `string` | —        | Replaces the hint and marks the control invalid |

Source: https://oyna-ui.org/components/input

---

# Textarea

Text of several lines. It looks and behaves like an [input](https://oyna-ui.org/components/input.md), and works inside an `OField` the same way.

```vue
<OField label="About you" hint="Up to 160 characters" :error="error">
  <OTextarea v-model="bio" placeholder="A few words" />
</OField>
```

It is three rows high and the user can drag it taller. Every attribute goes to the `<textarea>`: `rows`, `maxlength`, `placeholder`.

Hotkeys are ignored while the user types in it, as in any field.

## Props

| Prop      | Type      | Default | Description                                                       |
| --------- | --------- | ------- | ----------------------------------------------------------------- |
| `v-model` | `string`  | —       |                                                                   |
| `invalid` | `boolean` | `false` | A danger ring. Inside an `OField` with an error it is set for you |

Source: https://oyna-ui.org/components/textarea

---

# PinInput

A short code typed one character per cell: a confirmation code from an email or a text message, a PIN.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const code = ref('')
</script>

<template>
  <OPinInput v-model="code" aria-label="Confirmation code" />
</template>
```

The value is one string. Typing moves to the next cell, Backspace goes back, the arrow keys move between cells, and a code pasted into any cell fills them all. On a phone the number pad comes up and the code from a text message is offered above the keyboard.

Hotkeys are ignored while the user types in it, as in any field.

## In a field, with a check

`complete` fires when the last cell is filled: check the code there, without a button. Inside an [`OField`](https://oyna-ui.org/components/input.md) the label and the error are tied to the cells. `group` splits them the way the code is written.

Try `123456`, then any other code:

```vue
<script setup lang="ts">
const code = ref('')
const wrong = ref(false)

async function check(value: string) {
  wrong.value = !(await verify(value))
}
</script>

<template>
  <OField label="Code from the email" hint="Six digits" :error="wrong ? 'Not the code we sent. Try again.' : undefined">
    <OPinInput v-model="code" :group="3" @complete="check" @update:model-value="wrong = false" />
  </OField>
</template>
```

## Letters, length, hidden

`type="text"` takes any character. `length` sets the number of cells. `mask` hides what is typed.

```vue
<OPinInput v-model="invite" type="text" :length="5" aria-label="Invite code" />
<OPinInput v-model="pin" :length="4" mask aria-label="PIN" />
```

Without an `OField`, give it an `aria-label`.

## Props and events

| Prop       | Type                  | Default     | Description                                                       |
| ---------- | --------------------- | ----------- | ----------------------------------------------------------------- |
| `v-model`  | `string`              | `''`        | The code; shorter than `length` while it is being typed           |
| `length`   | `number`              | `6`         | How many characters the code has                                  |
| `type`     | `'numeric' \| 'text'` | `'numeric'` | Digits only, or any character                                     |
| `group`    | `number`              | —           | Splits the cells into groups of this many                         |
| `mask`     | `boolean`             | `false`     | Hides what is typed                                               |
| `invalid`  | `boolean`             | `false`     | A danger ring. Inside an `OField` with an error it is set for you |
| `disabled` | `boolean`             | `false`     |                                                                   |

| Event      | Payload  | Description          |
| ---------- | -------- | -------------------- |
| `complete` | `string` | Every cell is filled |

Built on [Reka UI](https://reka-ui.com) PinInput.

Source: https://oyna-ui.org/components/pin-input

---

# Checkbox

A yes or no that is part of a form and takes effect when the form is sent. For a setting that applies at once, use a [switch](https://oyna-ui.org/components/switch.md).

```vue
<script setup lang="ts">
import { ref } from 'vue'

const agree = ref(false)
</script>

<template>
  <OCheckbox v-model="agree"> I accept the terms </OCheckbox>
</template>
```

Inside is a real `<input type="checkbox">`: Space toggles it, a form submits it. `class` and `style` go to the label; every other attribute — `name`, `required`, `aria-label` — goes to the input.

Without text in the slot, give it an `aria-label`.

## Props

| Prop       | Type      | Default | Description |
| ---------- | --------- | ------- | ----------- |
| `v-model`  | `boolean` | `false` |             |
| `disabled` | `boolean` | `false` |             |

Source: https://oyna-ui.org/components/checkbox

---

# Radio

One choice out of a few, with all options in view. For a short switch between views use [tabs](https://oyna-ui.org/components/tabs.md); for a long list, a [select](https://oyna-ui.org/components/select.md).

```vue
<script setup lang="ts">
import { ref } from 'vue'

const plan = ref('pro')
const plans = [
  { value: 'free', label: 'Free', hint: 'One project, community support' },
  { value: 'pro', label: 'Pro', hint: 'Unlimited projects, email support' },
  { value: 'team', label: 'Team', hint: 'Shared workspaces, roles' },
  { value: 'enterprise', label: 'Enterprise', hint: 'Talk to us', disabled: true },
]
</script>

<template>
  <ORadio v-model="plan" :items="plans" label="Plan" />
</template>
```

`ORadio` is the whole group. `label` is the question the options answer; without it, give the group an `aria-label`. Arrow keys move between options.

## Props

| Prop       | Type                                                                    | Default  | Description                     |
| ---------- | ----------------------------------------------------------------------- | -------- | ------------------------------- |
| `items`    | `{ value: string, label: string, hint?: string, disabled?: boolean }[]` | required |                                 |
| `v-model`  | `string`                                                                | —        | The chosen item's `value`       |
| `label`    | `string`                                                                | —        | The question the options answer |
| `disabled` | `boolean`                                                               | `false`  | Disables every option           |

Source: https://oyna-ui.org/components/radio

---

# Switch

A setting that is on or off and applies at once. The label is on the left and the switch on the right, so a column of them lines up.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const email = ref(true)
</script>

<template>
  <OSwitch v-model="email"> Email notifications </OSwitch>
</template>
```

The switch changes at once: the thumb does not slide and the colour does not fade. The library answers with light, not movement, and a fade under a thumb that has already jumped looks like a stutter.

## Switch, toggle or checkbox

- **Switch** — a row in a list of settings.
- **[Toggle](https://oyna-ui.org/components/toggle.md)** — a chip in a toolbar, with a hotkey.
- **[Checkbox](https://oyna-ui.org/components/checkbox.md)** — a field of a form that is sent later.

## Props

| Prop       | Type      | Default | Description |
| ---------- | --------- | ------- | ----------- |
| `v-model`  | `boolean` | `false` |             |
| `disabled` | `boolean` | `false` |             |

`class` and `style` go to the label; every other attribute goes to the input inside.

Source: https://oyna-ui.org/components/switch

---

# Toggle

A setting that is on or off, as a chip. It lights up in the accent colour when on, and can own a hotkey.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const sound = ref(true)
const hints = ref(false)
</script>

<template>
  <OToggle v-model="sound" hotkey="KeyM"> Sound </OToggle>
  <OToggle v-model="hints" hotkey="KeyH"> Hints </OToggle>
</template>
```

Press `M` or `H` on this page. See [Hotkeys](https://oyna-ui.org/guide/hotkeys.md) for when a key is ignored.

## Props

| Prop          | Type      | Default       | Description                                                                |
| ------------- | --------- | ------------- | -------------------------------------------------------------------------- |
| `v-model`     | `boolean` | `false`       |                                                                            |
| `hotkey`      | `string`  | —             | Physical key (`KeyboardEvent.code`) that flips the toggle; shown inside it |
| `hotkeyLabel` | `string`  | from `hotkey` | Text shown for the key                                                     |
| `disabled`    | `boolean` | `false`       | Also turns the hotkey off                                                  |

Source: https://oyna-ui.org/components/toggle

---

# Tabs

A choice of one view out of a few. Arrow keys move between tabs.

## Segmented

Pills in a dark track. Without panels it is a switch: bind `v-model` and use the value yourself.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const period = ref('week')
const periods = [
  { value: 'today', label: 'Today' },
  { value: 'week', label: 'Week' },
  { value: 'all', label: 'All time' },
]
</script>

<template>
  <OTabs v-model="period" :items="periods" />
</template>
```

## Underline, with panels

For the sections of a page. A slot named after an item's `value` is its panel. Without a `v-model` the first tab is open.

```vue
<OTabs :items="sections" variant="underline">
  <template #overview>Everything at a glance.</template>
  <template #history>What happened before.</template>
  <template #settings>What can be changed.</template>
</OTabs>
```

## Props

| Prop      | Type                                                     | Default       | Description            |
| --------- | -------------------------------------------------------- | ------------- | ---------------------- |
| `items`   | `{ value: string, label: string, disabled?: boolean }[]` | required      |                        |
| `v-model` | `string`                                                 | first item    | The open tab's `value` |
| `variant` | `'segmented' \| 'underline'`                             | `'segmented'` |                        |

Built on [Reka UI](https://reka-ui.com) Tabs.

Source: https://oyna-ui.org/components/tabs

---

# Accordion

Sections that open one under another, so a long page shows its headings first: a list of questions, the groups of a settings page, the details of a deploy.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref('billing')
const questions = [
  { value: 'billing', label: 'How is usage billed?' },
  { value: 'limits', label: 'What are the rate limits?' },
  { value: 'regions', label: 'Where does my code run?' },
  { value: 'sso', label: 'Is there single sign-on?', disabled: true },
]
</script>

<template>
  <OAccordion v-model="open" :items="questions">
    <template #billing>By the request, counted per project.</template>
    <template #limits>A thousand requests a minute per token.</template>
    <template #regions>In the region of the project.</template>
    <template #sso>On the Enterprise plan.</template>
  </OAccordion>
</template>
```

Each item has a slot named after its `value`, as in [tabs](https://oyna-ui.org/components/tabs.md). One section is open at a time; a click on the open one closes it. The arrow keys move between the headings, `Enter` or `Space` opens one.

Without a `v-model` every section starts closed.

A section appears with a fade and at its full height at once: nothing slides.

## Several open at once

With `multiple` the sections open and close on their own, and the model is a list.

```vue
<script setup lang="ts">
const open = ref(['limits'])
</script>

<template>
  <OAccordion v-model="open" :items="questions" multiple>…</OAccordion>
</template>
```

## Accordion or tabs

Tabs when the sections are few, equal, and one of them must always be shown. An accordion when there are many, when a reader wants to scan the headings, or when two of them are worth comparing side by side.

## Props

| Prop       | Type                                                     | Default  | Description                                    |
| ---------- | -------------------------------------------------------- | -------- | ---------------------------------------------- |
| `items`    | `{ value: string, label: string, disabled?: boolean }[]` | required | A slot named after each `value` is its content |
| `v-model`  | `string`, or `string[]` with `multiple`                  | —        | The open section or sections                   |
| `multiple` | `boolean`                                                | `false`  | Several sections may be open at once           |

Built on [Reka UI](https://reka-ui.com) Accordion.

Source: https://oyna-ui.org/components/accordion

---

# Select

A choice of one out of a list that is too long for [tabs](https://oyna-ui.org/components/tabs.md). Arrow keys move through the list, typing jumps to an option, `Esc` closes it.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const language = ref('en')
const languages = [
  { value: 'en', label: 'English', hint: 'en' },
  { value: 'uz', label: 'Oʻzbekcha', hint: 'uz' },
  { value: 'ru', label: 'Русский', hint: 'ru' },
  { value: 'de', label: 'Deutsch', hint: 'de', disabled: true },
]
</script>

<template>
  <OSelect v-model="language" :items="languages" aria-label="Language" />
</template>
```

`hint` is a dim note at the end of an option. Give the select an `aria-label`, or put it in an [`OField`](https://oyna-ui.org/components/input.md)-like layout with your own label.

While the list is open, page hotkeys are off: typing a letter searches the list and must not trigger a button.

## Props

| Prop          | Type                                                                    | Default  | Description                   |
| ------------- | ----------------------------------------------------------------------- | -------- | ----------------------------- |
| `items`       | `{ value: string, label: string, hint?: string, disabled?: boolean }[]` | required |                               |
| `v-model`     | `string`                                                                | —        | The chosen item's `value`     |
| `placeholder` | `string`                                                                | —        | Shown while nothing is chosen |
| `disabled`    | `boolean`                                                               | `false`  |                               |

Built on [Reka UI](https://reka-ui.com) Select.

Source: https://oyna-ui.org/components/select

---

# Combobox

A choice of one out of a long list, found by typing. Use a [select](https://oyna-ui.org/components/select.md) while the list fits on the screen; once it does not, a field that filters the list is faster than scrolling.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const zone = ref('Asia/Tashkent')
const zones = [
  { value: 'Europe/London', label: 'London', hint: 'UTC+0' },
  { value: 'Europe/Berlin', label: 'Berlin', hint: 'UTC+1' },
  { value: 'Asia/Tashkent', label: 'Tashkent', hint: 'UTC+5' },
  // …
]
</script>

<template>
  <OCombobox v-model="zone" :items="zones" aria-label="Time zone" />
</template>
```

Typing narrows the list to the items whose label contains the text. The arrow keys move through it, `Enter` chooses, `Esc` closes. Leaving the field without choosing puts the chosen item's label back: the value is always one of the items, never a loose piece of text.

It looks like an [input](https://oyna-ui.org/components/input.md) and takes the full width of its container, so it sits in an `OField` like one.

## Placeholder and nothing found

```vue
<OCombobox v-model="region" :items="regions" placeholder="Region" empty-text="No such region" aria-label="Region" />
```

## Disabled

```vue
<OCombobox :items="regions" placeholder="Region" disabled aria-label="Region" />
```

## Props

| Prop          | Type                                                                    | Default           | Description                         |
| ------------- | ----------------------------------------------------------------------- | ----------------- | ----------------------------------- |
| `items`       | `{ value: string, label: string, hint?: string, disabled?: boolean }[]` | required          |                                     |
| `v-model`     | `string`                                                                | —                 | The chosen item's `value`           |
| `placeholder` | `string`                                                                | —                 | Shown while nothing is chosen       |
| `emptyText`   | `string`                                                                | `'Nothing found'` | Shown when nothing matches the text |
| `disabled`    | `boolean`                                                               | `false`           |                                     |

`class` and `style` go to the wrapper; other attributes (`aria-label`, `name`) go to the field.

Built on [Reka UI](https://reka-ui.com) Combobox.

Source: https://oyna-ui.org/components/combobox

---

# Slider

A number picked by dragging, when the feel of the value matters more than its exact digits: a volume, a radius, an opacity. For an exact number use an [input](https://oyna-ui.org/components/input.md).

```vue
<script setup lang="ts">
import { ref } from 'vue'

const radius = ref(14)
</script>

<template>
  <span>Radius · {{ radius }}px</span>
  <OSlider v-model="radius" :max="24" aria-label="Radius" />
</template>
```

The arrow keys move the thumb by one step, `Page Up` and `Page Down` by a larger one, `Home` and `End` go to the ends. The slider does not print its value: show it next to the label, as above.

Give it an `aria-label`: it goes to the thumb, which is the control a screen reader meets.

## Step

`step` is the distance between two values the thumb can stop at.

```vue
<OSlider v-model="glass" :min="10" :max="70" :step="5" aria-label="Glass darkness" />
```

## Disabled

```vue
<OSlider v-model="volume" disabled aria-label="Volume" />
```

## Props

| Prop       | Type      | Default | Description                 |
| ---------- | --------- | ------- | --------------------------- |
| `v-model`  | `number`  | `0`     | The value                   |
| `min`      | `number`  | `0`     |                             |
| `max`      | `number`  | `100`   |                             |
| `step`     | `number`  | `1`     | Distance between two values |
| `disabled` | `boolean` | `false` |                             |

`class` and `style` go to the slider; other attributes (`aria-label`, `name`) go to the thumb.

Built on [Reka UI](https://reka-ui.com) Slider.

Source: https://oyna-ui.org/components/slider

---

# KeyCapture

Lets the user choose a key. Click it, then press the key; `Esc` or clicking away cancels. The value is a physical key code, ready to pass to a `hotkey`.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const retry = ref('KeyR')
</script>

<template>
  <OKeyCapture v-model="retry"> Retry </OKeyCapture>
  <OButton variant="soft" :hotkey="retry" @click="retry"> Retry </OButton>
</template>
```

Change the first key above, then press the new one: the button follows.

While it waits, the key cap gets the accent ring, and the press goes to the capture only: no hotkey on the page reacts to it.

Checking that two actions do not share a key is up to you.

## Props

| Prop       | Type      | Default | Description                         |
| ---------- | --------- | ------- | ----------------------------------- |
| `v-model`  | `string`  | —       | Physical key (`KeyboardEvent.code`) |
| `disabled` | `boolean` | `false` |                                     |

The slot is the caption under the key.

Source: https://oyna-ui.org/components/key-capture

---

# Dialog

A layer over the page for something that needs an answer or full attention. `Esc`, the close button and a click outside close it; focus stays inside while it is open and returns to where it was.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <OButton hotkey="KeyD" @click="open = true"> Open dialog </OButton>

  <ODialog v-model:open="open" title="Settings" description="Kept on this device.">
    <OField label="Name" hint="2–16 characters">
      <OInput v-model="name" />
    </OField>
    <OToggle v-model="sound" hotkey="KeyM"> Sound </OToggle>
    <OButton variant="primary" hotkey="Enter" @click="save"> Save </OButton>
  </ODialog>
</template>
```

## Hotkeys and layers

While a dialog is open, hotkeys of everything behind it are off: on this page `D` does nothing while the dialog is open. Hotkeys of buttons and toggles inside the dialog work. With a dialog opened from a dialog, only the top one answers, and `Esc` closes them one at a time.

## Look

The dialog is nearly opaque on purpose: glass over blurred glass over a busy background is hard to read. Its width is `520px`; set `--o-dialog-width` to change it. A class or a style on `ODialog` goes to the dialog box.

```vue
<ODialog v-model:open="open" title="Wide" style="--o-dialog-width: 720px">
  …
</ODialog>
```

## Props

| Prop           | Type      | Default   | Description                                   |
| -------------- | --------- | --------- | --------------------------------------------- |
| `v-model:open` | `boolean` | `false`   |                                               |
| `title`        | `string`  | required  |                                               |
| `description`  | `string`  | —         | A line under the title, read out with it      |
| `closeLabel`   | `string`  | `'Close'` | Text of the close button, after the `Esc` key |

Built on [Reka UI](https://reka-ui.com) Dialog.

Source: https://oyna-ui.org/components/dialog

---

# Command

A list of everything the app can do, opened with one key and searched by typing: the fastest way around an interface for someone who keeps their hands on the keyboard.

```vue
<script setup lang="ts">
import { Palette, Rocket, RotateCcw, Settings, Terminal } from '@lucide/vue'
import type { CommandItem } from 'oyna-ui'
import { ref } from 'vue'

const open = ref(false)
const commands: CommandItem[] = [
  { value: 'deploy', label: 'Deploy to production', group: 'Deploys', icon: Rocket, hint: 'v1.4.1' },
  { value: 'rollback', label: 'Roll back', group: 'Deploys', icon: RotateCcw, keywords: 'revert undo' },
  { value: 'logs', label: 'Open the logs', group: 'Deploys', icon: Terminal },
  { value: 'theme', label: 'Theme editor', group: 'Go to', icon: Palette },
  { value: 'settings', label: 'Settings', group: 'Go to', icon: Settings, keywords: 'preferences account' },
  { value: 'billing', label: 'Billing', group: 'Go to', disabled: true, hint: 'owners only' },
]

function run(item: CommandItem) {
  // item.value tells which one
}
</script>

<template>
  <OButton hotkey="KeyK" @click="open = true">Commands</OButton>
  <OCommand v-model:open="open" :items="commands" @select="run" />
</template>
```

The field has the focus as soon as the palette opens. The arrow keys move through the list, `Enter` runs the lit item, `Esc` closes. Choosing an item closes the palette and emits `select` with that item; what it does is up to you.

## How it searches

Every typed word must occur in the item's `label`, `group` or `keywords`, in any order: `dep prod` finds "Deploy to production", and `undo` finds "Roll back" through its keywords. Put the words people might try, but which are not on the label, into `keywords`.

## Opening it

The palette has no key of its own. Open it from a button that owns a hotkey, as above, or with [`useHotkey`](https://oyna-ui.org/guide/hotkeys.md). Hotkeys are single physical keys, so the palette here opens on `K`; a combination such as Ctrl+K is yours to listen for.

## Your own search

By default the palette filters `items` itself. With `:filter="false"` it shows them as given, and tells you what is typed through `v-model:query`: the search is then yours — a request to a server, or one with its own idea of what comes first. An item's `description` is a second, dimmer line under its label, for the words around a match.

```vue
<script setup lang="ts">
import type { CommandItem } from 'oyna-ui'
import { ref, watch } from 'vue'

const open = ref(false)
const query = ref('')
const results = ref<CommandItem[]>([])

watch(query, async (text) => {
  const found = await search(text)
  results.value = found.map((page) => ({
    value: page.url,
    label: page.title,
    hint: page.section,
    description: page.excerpt,
  }))
})
</script>

<template>
  <OCommand v-model:open="open" v-model:query="query" :items="results" :filter="false" title="Search" @select="go">
    <template #footer>
      <span><OKbd>↑</OKbd> <OKbd>↓</OKbd> to choose · <OKbd>Enter</OKbd> to open</span>
    </template>
  </OCommand>
</template>
```

The `footer` slot stands under the list. The search of this site (press `/`) is built exactly this way.

## Without groups

Items without a `group` form one plain list. `title`, `placeholder` and `empty-text` set the words.

```vue
<OCommand
  v-model:open="open"
  :items="pages"
  title="Go to"
  placeholder="A page"
  empty-text="No such page"
  @select="go"
/>
```

## Props

| Prop            | Type            | Default            | Description                                                |
| --------------- | --------------- | ------------------ | ---------------------------------------------------------- |
| `items`         | `CommandItem[]` | required           |                                                            |
| `v-model:open`  | `boolean`       | `false`            |                                                            |
| `title`         | `string`        | `'Commands'`       | The dialog's title                                         |
| `placeholder`   | `string`        | `'Type a command'` |                                                            |
| `emptyText`     | `string`        | `'Nothing found'`  | Shown when nothing matches the text                        |
| `filter`        | `boolean`       | `true`             | `false` shows the items as given: you narrow them yourself |
| `v-model:query` | `string`        | `''`               | What is typed in the field                                 |

## CommandItem

| Field         | Type        | Description                                             |
| ------------- | ----------- | ------------------------------------------------------- |
| `value`       | `string`    | What tells the items apart                              |
| `label`       | `string`    | The text of the row                                     |
| `group`       | `string`    | Items with the same group stand together under its name |
| `hint`        | `string`    | A dim note at the end of the row                        |
| `description` | `string`    | A second, dimmer line under the label                   |
| `keywords`    | `string`    | Extra words the item is found by                        |
| `icon`        | `Component` | An icon component, e.g. from Lucide                     |
| `disabled`    | `boolean`   |                                                         |

## Slots

| Slot     | Description                                   |
| -------- | --------------------------------------------- |
| `footer` | Under the list: a hint about the keys, a link |

## Events

| Event    | Payload       | Description        |
| -------- | ------------- | ------------------ |
| `select` | `CommandItem` | An item was chosen |

Built on [Reka UI](https://reka-ui.com) Listbox, inside a [dialog](https://oyna-ui.org/components/dialog.md).

Source: https://oyna-ui.org/components/command

---

# Drawer

A panel standing at an edge of the screen, for something longer than a [popover](https://oyna-ui.org/components/popover.md) holds and less final than a [dialog](https://oyna-ui.org/components/dialog.md): filters, the details of a row, a short form. The page stays behind it.

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <OButton hotkey="KeyF" @click="open = true">Filters</OButton>

  <ODrawer v-model:open="open" title="Filters" description="Applied to the list of requests.">
    <OSwitch v-model="onlyErrors">Only errors</OSwitch>
    <OSwitch v-model="slow">Slower than 1 s</OSwitch>
    <OButton variant="primary" hotkey="Enter" @click="apply">Apply</OButton>
  </ODrawer>
</template>
```

A drawer is a dialog in another place: the same header, the same `Esc`, focus kept inside, and hotkeys of the page switched off while it is open. Everything on the [Dialog](https://oyna-ui.org/components/dialog.md) page about focus and hotkeys holds here.

It fades in and does not slide: the library uses light, not movement.

## Sides

`side` is `right` (the default), `left` or `bottom`. A bottom drawer is a sheet: on a phone it is the natural place for a menu or a set of filters, within reach of the thumb.

```vue
<ODrawer v-model:open="open" title="Navigation" side="left">…</ODrawer>

<ODrawer v-model:open="open" title="Share" side="bottom">…</ODrawer>
```

## Size

A side drawer is 420px wide and never wider than the screen; a sheet is at most 85% of the screen's height and scrolls inside. Change either with a CSS variable:

```vue
<ODrawer v-model:open="open" title="Details" style="--o-drawer-width: 560px">…</ODrawer>

<ODrawer v-model:open="open" title="Share" side="bottom" style="--o-drawer-height: 50dvh">…</ODrawer>
```

## Props

| Prop           | Type                            | Default   | Description                              |
| -------------- | ------------------------------- | --------- | ---------------------------------------- |
| `title`        | `string`                        | required  |                                          |
| `v-model:open` | `boolean`                       | `false`   |                                          |
| `description`  | `string`                        | —         | A line under the title, read out with it |
| `side`         | `'right' \| 'left' \| 'bottom'` | `'right'` | The edge it stands at                    |
| `closeLabel`   | `string`                        | `'Close'` | Text of the close button                 |

Built on the library's [Dialog](https://oyna-ui.org/components/dialog.md), which is [Reka UI](https://reka-ui.com) Dialog.

Source: https://oyna-ui.org/components/drawer

---

# Popover

A small panel that opens from a button and can hold anything: a few filters, a short form, an explanation. A click outside or `Esc` closes it.

```vue
<OPopover>
  <OButton>Filters</OButton>

  <template #content="{ close }">
    <OSwitch v-model="onlyErrors">Only errors</OSwitch>
    <OSwitch v-model="slow">Slower than 1 s</OSwitch>
    <OButton variant="primary" hotkey="Enter" @click="close">Apply</OButton>
  </template>
</OPopover>
```

The default slot takes exactly one element that can receive focus; it becomes the trigger. The `content` slot gets a `close` function.

## Popover, tooltip, dialog or dropdown menu

- **[Tooltip](https://oyna-ui.org/components/tooltip.md)** — one line, on hover, nothing to click.
- **[DropdownMenu](https://oyna-ui.org/components/dropdown-menu.md)** — a list of actions.
- **Popover** — anything else that is small and belongs to one place on the page.
- **[Dialog](https://oyna-ui.org/components/dialog.md)** — something that needs the whole of the user's attention.

## Confirming an action

There is no separate "popconfirm" component: a popover with a line of text and two buttons is one. Give the confirming button `hotkey="Enter"`, so the question can be answered without the mouse; `Esc` is the "no".

```vue
<OPopover align="center">
  <OButton>Clear the cache</OButton>

  <template #content="{ close }">
    <span>Clear the cache of <b>public-api</b>? The next requests will be slower until it fills again.</span>
    <OButton size="sm" variant="ghost" @click="close">Keep it</OButton>
    <OButton size="sm" variant="primary" hotkey="Enter" @click="clearCache(close)">Clear</OButton>
  </template>
</OPopover>
```

Keep this for small things that can be done again or undone. Something that cannot be taken back — deleting a project, revoking a token — deserves a [dialog](https://oyna-ui.org/components/dialog.md): it has room to say what will be lost, and it cannot be dismissed by a stray click.

## Hotkeys and width

Hotkeys of controls inside an open popover work; the ones behind it are off, as with a dialog.

The panel is `280px` wide; set `--o-popover-width` on an element around it, or on `:root`, to change it.

## Props

| Prop           | Type                                     | Default    | Description                                       |
| -------------- | ---------------------------------------- | ---------- | ------------------------------------------------- |
| `v-model:open` | `boolean`                                | `false`    |                                                   |
| `side`         | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Flips when there is no room                       |
| `align`        | `'start' \| 'center' \| 'end'`           | `'start'`  | Which edge of the trigger the panel lines up with |

Built on [Reka UI](https://reka-ui.com) Popover.

Source: https://oyna-ui.org/components/popover

---

# DropdownMenu

A menu of actions that drops down from a button. Arrow keys move through it, typing jumps to an item, `Esc` closes it.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from 'oyna-ui'
import { Archive, Copy, Pencil, Trash2 } from '@lucide/vue'

const items: DropdownMenuItem[] = [
  { label: 'Rename', icon: Pencil, hint: 'F2', onSelect: rename },
  { label: 'Duplicate', icon: Copy, onSelect: duplicate },
  { label: 'Archive', icon: Archive, disabled: true },
  { separator: true },
  { label: 'Delete', icon: Trash2, tone: 'danger', onSelect: remove },
]
</script>

<template>
  <ODropdownMenu :items="items">
    <OButton>Actions</OButton>
  </ODropdownMenu>
</template>
```

The slot takes exactly one element that can receive focus; it becomes the trigger.

- `icon` is an icon component, such as one from [Lucide](https://oyna-ui.org/guide/icons.md). Give icons to all items of a menu or to none.
- `hint` is a dim note at the end of an item. It only shows text: binding the key is up to you.
- `tone: 'danger'` is for the action that destroys something. One per menu, last, after a separator.

A menu is for actions. To choose a value, use a [select](https://oyna-ui.org/components/select.md). For the same items on a right click, there is a [context menu](https://oyna-ui.org/components/context-menu.md).

While the menu is open, page hotkeys are off.

## Props

| Prop    | Type                                     | Default    | Description                                                                     |
| ------- | ---------------------------------------- | ---------- | ------------------------------------------------------------------------------- |
| `items` | `DropdownMenuItem[]`                     | required   | `{ label, icon?, hint?, tone?, disabled?, onSelect? }` or `{ separator: true }` |
| `side`  | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Flips when there is no room                                                     |
| `align` | `'start' \| 'center' \| 'end'`           | `'start'`  | Which edge of the trigger the menu lines up with                                |

Built on [Reka UI](https://reka-ui.com) DropdownMenu.

Source: https://oyna-ui.org/components/dropdown-menu

---

# ContextMenu

A menu of actions that opens where the pointer is, on a right click: the actions of the thing that was clicked. On a touch screen a long press opens it.

```vue
<script setup lang="ts">
import { Archive, Copy, Pencil, Trash2 } from '@lucide/vue'
import type { DropdownMenuItem } from 'oyna-ui'

const items: DropdownMenuItem[] = [
  { label: 'Rename', icon: Pencil, hint: 'F2', onSelect: rename },
  { label: 'Duplicate', icon: Copy, onSelect: duplicate },
  { label: 'Archive', icon: Archive, disabled: true },
  { separator: true },
  { label: 'Delete', icon: Trash2, tone: 'danger', onSelect: remove },
]
</script>

<template>
  <OContextMenu :items="items">
    <OSurface>public-api</OSurface>
  </OContextMenu>
</template>
```

The default slot takes exactly one element; a right click anywhere on it opens the menu. The items are the ones a [dropdown menu](https://oyna-ui.org/components/dropdown-menu.md) takes, and the menu looks and behaves the same: arrow keys, typing to jump, `Esc`.

## Never the only way

A context menu is invisible until someone thinks to right-click, and many people never do. Put every action it holds somewhere in plain sight as well: a [dropdown menu](https://oyna-ui.org/components/dropdown-menu.md) behind a button with three dots can take the very same `items`.

It also replaces the browser's own menu on that element, with its "copy" and "open in a new tab". Do not wrap text people may want to copy, or a whole page.

## Disabled

With `disabled` a right click does what the browser does, as if the menu were not there.

```vue
<OContextMenu :items="items" :disabled="readOnly">…</OContextMenu>
```

## Props

| Prop       | Type                 | Default  | Description                                                                     |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------- |
| `items`    | `DropdownMenuItem[]` | required | `{ label, icon?, hint?, tone?, disabled?, onSelect? }` or `{ separator: true }` |
| `disabled` | `boolean`            | `false`  | Leaves the right click to the browser                                           |

Built on [Reka UI](https://reka-ui.com) ContextMenu.

Source: https://oyna-ui.org/components/context-menu

---

# Tooltip

A short note about a control, shown on hover and on keyboard focus. For controls whose meaning is not written on them, such as icon buttons.

A finger cannot hover, so on a touch screen a tooltip does not open. Keep it for hints a phone user can do without, and give icon buttons an `aria-label`.

```vue
<OTooltip text="Help">
  <OButton icon shape="pill" aria-label="Help"><CircleHelp /></OButton>
</OTooltip>

<OTooltip text="Shown below" side="bottom">
  <OButton>Bottom</OButton>
</OTooltip>
```

The slot takes exactly one element that can receive focus: a button, a link, a toggle. It becomes the trigger.

A tooltip is not a place for something the user must read: it is not shown on touch screens. Keep the `aria-label` on an icon button.

## Props

| Prop   | Type                                     | Default  | Description                 |
| ------ | ---------------------------------------- | -------- | --------------------------- |
| `text` | `string`                                 | required |                             |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'`  | Flips when there is no room |

Built on [Reka UI](https://reka-ui.com) Tooltip.

Source: https://oyna-ui.org/components/tooltip

---

# Toast

A short message about something that just happened. It goes away by itself; a click removes it sooner.

Put one `OToaster` in your app, then call `toast()` from anywhere:

```vue
<!-- App.vue -->
<template>
  <OBackground />
  <RouterView />
  <OToaster />
</template>
```

```ts
import { toast } from 'oyna-ui'

toast('Link copied')
toast('Saved', { tone: 'accent' })
toast('Could not save. Try again.', { tone: 'danger' })
toast('Stays until clicked', { duration: 0 })
```

A toast is plain by default. The ring is a signal here as everywhere: `accent` for the result the user was waiting for, `danger` for something that went wrong. A `danger` toast is announced by screen readers at once, the others when the reader is idle.

## API

`toast(message, options?)` returns the toast's id.

| Option     | Type                   | Default | Description                                    |
| ---------- | ---------------------- | ------- | ---------------------------------------------- |
| `tone`     | `'accent' \| 'danger'` | —       |                                                |
| `duration` | `number`               | `4000`  | In ms; `0` keeps the toast until it is clicked |

`dismissToast(id)` removes a toast.

Source: https://oyna-ui.org/components/toast

---

# Alert

A message that stays on the page, next to what it is about. For one that comes and goes, use a [toast](https://oyna-ui.org/components/toast.md).

```vue
<script setup lang="ts">
import { CircleCheck, Info, TriangleAlert } from '@lucide/vue'
</script>

<template>
  <OAlert title="Maintenance on Sunday, 02:00–03:00 UTC">
    <template #icon><Info /></template>
    Deploys are paused for that hour. Running services are not affected.
  </OAlert>

  <OAlert tone="accent" title="v1.4.1 is live">
    <template #icon><CircleCheck /></template>
    All 214 tests passed. Error rate is 0.3%.
  </OAlert>

  <OAlert tone="danger" title="GET /v1/search is degraded">
    <template #icon><TriangleAlert /></template>
    p95 is 1.9 s, nine times the usual.
    <template #actions>
      <OButton size="sm">Open the trace</OButton>
      <OButton size="sm" variant="ghost">Mute for an hour</OButton>
    </template>
  </OAlert>
</template>
```

## Tone

A plain alert has no ring: it is information. A toned one is a signal and gets the ring, like a [surface](https://oyna-ui.org/components/surface.md) with a `signal`:

- `accent` — good news, or the thing to do next;
- `danger` — something is wrong or at stake. It is also the only one a screen reader reads out at once.

There are two tones on purpose. The library has one accent and one danger colour, and no yellow "warning" in between: decide whether it is wrong or not.

## Closable

`closable` adds a close button. It emits `close`; hiding the alert is up to you.

```vue
<OAlert v-if="shown" title="You are on the free plan" closable @close="shown = false">
  One project and 10 000 requests a day.
</OAlert>
```

## Alert, toast or dialog

- **Alert** — a state of the page: it is true for as long as it is shown.
- **[Toast](https://oyna-ui.org/components/toast.md)** — an event: something just happened.
- **[Dialog](https://oyna-ui.org/components/dialog.md)** — a question that must be answered before going on.

## Props and slots

| Prop       | Type                   | Default | Description                             |
| ---------- | ---------------------- | ------- | --------------------------------------- |
| `title`    | `string`               | —       | What happened, in a few words           |
| `tone`     | `'accent' \| 'danger'` | —       |                                         |
| `closable` | `boolean`              | `false` | Shows a close button that emits `close` |

| Slot      | Description                                              |
| --------- | -------------------------------------------------------- |
| default   | The details                                              |
| `icon`    | An icon before the text; it takes the colour of the tone |
| `actions` | One or two buttons: what to do about it                  |

Source: https://oyna-ui.org/components/alert

---

# Spinner

Something is under way and there is nothing to show yet. Three dots light up in turn: the library signals with light, so nothing rotates.

```vue
<OSpinner />
<OSpinner label="Loading the report" />
<OButton loading>Saving</OButton>
```

It takes the size and the colour of the text around it. `label` is what a screen reader says; the default is "Loading".

A [button](https://oyna-ui.org/components/button.md) has a `loading` prop that shows a spinner inside it and stops clicks and the hotkey.

When the user asks for reduced motion, the dots stop and stay half lit.

## Spinner or skeleton

- **Spinner** — an action is running: saving, sending, deploying.
- **[Skeleton](https://oyna-ui.org/components/skeleton.md)** — content is on its way and you know its shape.

## Props

| Prop    | Type     | Default     | Description                         |
| ------- | -------- | ----------- | ----------------------------------- |
| `label` | `string` | `'Loading'` | What is loading, for screen readers |

Source: https://oyna-ui.org/components/spinner

---

# Skeleton

A placeholder in the shape of content that is still loading, so the page does not jump when it arrives.

```vue
<OSkeleton style="width: 40%; height: 12px" />
<OSkeleton style="height: 34px" />
<OSkeleton style="width: 70%" />
<OSkeleton style="width: 56px; height: 56px; border-radius: 50%" />
```

It is a block one line of text high and as wide as its container. Give it the width and height of what it stands for, with a class or a style.

A skeleton is hidden from screen readers. Mark the region that is loading with `aria-busy="true"` so they know to wait:

```vue
<OCard :aria-busy="loading">
  <template v-if="loading">
    <OSkeleton style="width: 40%; height: 12px" />
    <OSkeleton style="height: 34px" />
  </template>
  <OStat v-else label="Requests">{{ requests }}</OStat>
</OCard>
```

When the user asks for reduced motion, the pulse stops.

Source: https://oyna-ui.org/components/skeleton

---

# Empty

Nothing here yet. Say what is missing, why, and give the way out.

```vue
<script setup lang="ts">
import { Inbox, Plus } from '@lucide/vue'
</script>

<template>
  <OEmpty title="No deploys yet">
    <template #icon><Inbox /></template>
    Ship the first version and it will show up here.
    <template #actions>
      <OButton variant="primary"><Plus /> New deploy</OButton>
      <OButton variant="ghost">Read the guide</OButton>
    </template>
  </OEmpty>
</template>
```

Only the title is required. A search with no results needs no button:

```vue
<OEmpty title="Nothing found">Try a shorter word.</OEmpty>
```

It has no fill of its own: put it in a [card](https://oyna-ui.org/components/surface.md), or straight on the page.

## Props and slots

| Prop    | Type     | Default  | Description                     |
| ------- | -------- | -------- | ------------------------------- |
| `title` | `string` | required | What is missing, in a few words |

| Slot      | Description                             |
| --------- | --------------------------------------- |
| default   | Why it is empty, or what to do about it |
| `icon`    | An icon above the title                 |
| `actions` | One or two buttons: the way out         |

Source: https://oyna-ui.org/components/empty

---

# Stat

A number with a caption. The value is set in the display face with tabular figures, so numbers in a row line up.

```vue
<OStat label="Requests">
18 204
</OStat>

<OStat label="Median">
142 ms
</OStat>

<OStat label="Best" tone="accent">
96 ms
</OStat>

<OStat label="Errors" tone="danger">
12
</OStat>
```

Colour is a signal here too: `accent` for the best or the user's own number, `danger` for the one that needs attention. Most stats have no tone.

A stat is as wide as its content; put several in a grid to make them equal.

```vue
<div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 10px">
  <OStat v-for="stat in stats" :key="stat.label" :label="stat.label">
    {{ stat.value }}
  </OStat>
</div>
```

## Props

| Prop    | Type                   | Default  | Description       |
| ------- | ---------------------- | -------- | ----------------- |
| `label` | `string`               | required |                   |
| `tone`  | `'accent' \| 'danger'` | —        | Colours the value |

Source: https://oyna-ui.org/components/stat

---

# Progress

How much is done, or how much is left.

```vue
<OProgress :value="72" aria-label="Storage used" />
```

The bar takes the width of its container. Give it an `aria-label`: a bar has no text of its own.

## Running out

Switch the tone to `danger` when what is left gets low. The threshold is yours to pick.

```vue
<OProgress :value="left" :tone="left < 30 ? 'danger' : 'accent'" aria-label="Time left" />
```

## Props

| Prop    | Type                   | Default    | Description |
| ------- | ---------------------- | ---------- | ----------- |
| `value` | `number`               | required   |             |
| `max`   | `number`               | `100`      |             |
| `tone`  | `'accent' \| 'danger'` | `'accent'` |             |

Source: https://oyna-ui.org/components/progress

---

# Pips

Progress through a small number of equal steps, one dot per step. For anything longer or continuous use [Progress](https://oyna-ui.org/components/progress.md).

```vue
<OPips :done="3" :total="8" aria-label="Steps done" />
```

## Marker

A point to compare with: a previous best, a rival, a deadline. It is counted in steps and may be fractional: `4.5` is halfway through the fifth step. Say in a caption what the marker is.

```vue
<OPips :done="3" :total="8" :marker="4.5" aria-label="Steps done" />

<span>
3 / 8 · ▼ your best
</span>
```

## Props

| Prop     | Type     | Default  | Description                       |
| -------- | -------- | -------- | --------------------------------- |
| `done`   | `number` | required |                                   |
| `total`  | `number` | required |                                   |
| `marker` | `number` | —        | A point to compare with, in steps |

Source: https://oyna-ui.org/components/pips

---

# Sparkline

The shape of a series in a small space: no axes, no numbers. The last value gets a dot in the accent colour — it is the one that matters.

```vue
<OSparkline :values="[12, 14, 13, 17, 16, 21, 19, 24, 23, 28]" label="Visits over ten days, rising to 28" />
```

The `label` is what a screen reader says instead of the picture: put the conclusion in it, not "chart".

## Lower is better

For times, ranks and error counts, turn the chart over so that an improvement still goes up.

```vue
<OSparkline :values="laps" lower-is-better :width="160" :height="40" label="Lap times, down to 7.8 s" />
```

## Tone

The dot is accent by default. Make it `danger` when the series ends somewhere bad.

```vue
<OSparkline :values="latency" lower-is-better tone="danger" label="Latency, climbing to 710 ms" />
```

## Props

| Prop            | Type                   | Default    | Description                              |
| --------------- | ---------------------- | ---------- | ---------------------------------------- |
| `values`        | `number[]`             | required   | Oldest first                             |
| `label`         | `string`               | required   | What the chart shows, for screen readers |
| `width`         | `number`               | `240`      | Shrinks to its container when narrower   |
| `height`        | `number`               | `56`       |                                          |
| `lowerIsBetter` | `boolean`              | `false`    | Smaller values sit higher                |
| `tone`          | `'accent' \| 'danger'` | `'accent'` | Colour of the last point                 |

Source: https://oyna-ui.org/components/sparkline

---

# BarChart

A few values side by side. All bars are quiet; colour picks out the one to look at.

```vue
<script setup lang="ts">
const week = [
  { label: 'Mon', value: 1.42, display: '1.42' },
  { label: 'Tue', value: 1.18, display: '1.18' },
  { label: 'Wed', value: 2.31, display: '2.31', tone: 'danger', dot: true },
  { label: 'Thu', value: 1.27, display: '1.27' },
  { label: 'Fri', value: 0.96, display: '0.96', tone: 'accent' },
  { label: 'Sat', value: 1.51, display: '1.51', dot: true },
  { label: 'Sun', value: 1.33, display: '1.33' },
]
</script>

<template>
  <OBarChart :items="week" />
</template>
```

- `tone` colours one bar and its value: `danger` for the worst, `accent` for the best. Use it on one or two bars, or it stops meaning anything.
- `dot` marks a bar where something happened — an error, a miss. Say what the dot means next to the chart.
- `display` is the value as text. Bars are scaled to the highest value.

## Many bars

With more than 12 bars the chart gets dense: thin bars, no text. The values stay in the hover titles.

## Height and labels

The chart is `180px` high; set `--o-bar-chart-height` to change it. The `label` slot replaces the text under a bar, for an icon or an avatar:

```vue
<OBarChart :items="week" style="--o-bar-chart-height: 240px">
  <template #label="{ item }">
    <img :src="item.icon" :alt="item.label">
  </template>
</OBarChart>
```

## Props

| Prop    | Type                                                                                               | Default  | Description |
| ------- | -------------------------------------------------------------------------------------------------- | -------- | ----------- |
| `items` | `{ label: string, value: number, display?: string, tone?: 'accent' \| 'danger', dot?: boolean }[]` | required |             |

Source: https://oyna-ui.org/components/bar-chart

---

# Table

Rows of the same kind. Rows are told apart by stripes, not by lines. Numeric columns are set in the display face with figures that line up.

```vue
<script setup lang="ts">
const columns = [
  { key: 'place', label: '#' },
  { key: 'name', label: 'Name' },
  { key: 'runs', label: 'Runs', numeric: true },
  { key: 'best', label: 'Best', numeric: true },
]
const rows = [
  { place: 1, name: 'ada', runs: 214, best: '18.42' },
  { place: 2, name: 'grace', runs: 97, best: '19.06' },
  { place: 3, name: 'you', runs: 152, best: '19.31' },
]
</script>

<template>
  <OTable :columns="columns" :rows="rows" row-key="name" :signal="(row) => (row.name === 'you' ? 'accent' : undefined)">
    <template #name="{ row, value }">
      <b>{{ value }}</b> <OBadge v-if="row.place === 1" tone="accent"> Leader </OBadge>
    </template>
  </OTable>
</template>
```

## Signal

`signal` gives a row a ring: `accent` for the user's own row, `danger` for one at stake. One row, rarely two.

## Cells

A slot named after a column's `key` draws that column's cells. It gets the `row` and the cell's `value`.

A column need not be a field of the row. For a column of buttons or a menu, give it any `key` and draw it with the slot:

```vue
<OTable :columns="[...columns, { key: 'actions', label: 'Actions' }]" :rows="rows">
  <template #actions="{ row }">
    <OButton size="sm" @click="open(row)">Open</OButton>
  </template>
</OTable>
```

## Hoverable

With `hoverable` the row under the pointer is lit a little. Use it when a row can be acted on — it has a menu, opens something, or is long enough that the eye loses it on the way across — and leave it off for a table that is only read.

```vue
<OTable :columns :rows row-key="name" hoverable />
```

A row with a signal keeps its colour and gets brighter. On a touch screen nothing is lit: there is no pointer to hover with.

## Row menu

`row-menu` is a function that gives the actions of a row; a right click on the row, or a long press on a touch screen, opens them as a [context menu](https://oyna-ui.org/components/context-menu.md). The items are the ones a [dropdown menu](https://oyna-ui.org/components/dropdown-menu.md) takes, so one function can feed both: the menu behind a button in the row, for everyone, and the right click, for those who look for it.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from 'oyna-ui'

function actionsOf(project: Project): DropdownMenuItem[] {
  return [
    { label: 'Archive', onSelect: () => archive(project) },
    { separator: true },
    { label: 'Delete', tone: 'danger', onSelect: () => remove(project) },
  ]
}
</script>

<template>
  <OTable :columns :rows row-key="name" :row-menu="actionsOf">
    <template #actions="{ row }">
      <ODropdownMenu :items="actionsOf(row)" align="end">
        <OButton icon size="sm" variant="ghost" :aria-label="`Actions for ${row.name}`"><Ellipsis /></OButton>
      </ODropdownMenu>
    </template>
  </OTable>
</template>
```

The [Projects](https://oyna-ui.org/examples/projects) example does exactly this.

## Props

| Prop        | Type                                                  | Default  | Description                            |
| ----------- | ----------------------------------------------------- | -------- | -------------------------------------- |
| `columns`   | `{ key: string, label: string, numeric?: boolean }[]` | required |                                        |
| `rows`      | `object[]`                                            | required |                                        |
| `rowKey`    | `string`                                              | position | The field that identifies a row        |
| `signal`    | `(row) => 'accent' \| 'danger' \| undefined`          | —        | A ring for a row that means something  |
| `hoverable` | `boolean`                                             | `false`  | Lights the row under the pointer       |
| `rowMenu`   | `(row) => DropdownMenuItem[]`                         | —        | The actions of a row, on a right click |

The table does not sort, page or scroll by itself. On a narrow screen, wrap it in an element with `overflow-x: auto`.

Source: https://oyna-ui.org/components/table

---

# Pagination

The way through a list too long for one screen: a row of page numbers with arrows at its ends.

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'

const page = ref(1)
const size = 5
const rows = computed(() => deploys.slice((page.value - 1) * size, page.value * size))
</script>

<template>
  <OTable :columns="columns" :rows="rows" row-key="version" />
  <OPagination v-model:page="page" :total="deploys.length" :page-size="size" />
</template>
```

It takes `total`, the number of items, not of pages, and works the pages out from `page-size`. It does not cut the list: show the rows of the current page yourself, as above, or ask the server for them.

## Many pages

The first and the last page are always shown; the far ones fold into a gap. `siblings` is how many pages stand on each side of the current one.

```vue
<OPagination v-model:page="page" :total="200" />
<OPagination v-model:page="page" :total="200" :siblings="2" />
```

## Disabled

```vue
<OPagination :total="50" disabled />
```

## Props

| Prop           | Type      | Default           | Description                                                     |
| -------------- | --------- | ----------------- | --------------------------------------------------------------- |
| `total`        | `number`  | required          | How many items there are in all                                 |
| `v-model:page` | `number`  | `1`               | The current page, from 1                                        |
| `pageSize`     | `number`  | `10`              | Items on one page                                               |
| `siblings`     | `number`  | `1`               | Pages on each side of the current one                           |
| `disabled`     | `boolean` | `false`           |                                                                 |
| `label`        | `string`  | `'Pages'`         | What a screen reader calls it; make it differ if a page has two |
| `prevLabel`    | `string`  | `'Previous page'` | Name of the left arrow                                          |
| `nextLabel`    | `string`  | `'Next page'`     | Name of the right arrow                                         |

Built on [Reka UI](https://reka-ui.com) Pagination.

Source: https://oyna-ui.org/components/pagination

---

# Timeline

What happened, in order. A dot for every event on one track; the dot's colour is the signal.

```vue
<script setup lang="ts">
const release = [
  { title: 'v1.4.1 is live', time: '2 min ago', text: 'Production · 3 commits from main', tone: 'accent' },
  { title: 'Tests passed', time: '4 min ago', text: '214 tests in 38 s' },
  { title: 'Build finished', time: '5 min ago' },
  { title: 'Deploy started by ada', time: '6 min ago' },
]
</script>

<template>
  <OTimeline :items="release" />
</template>
```

Only `title` is required. The order is yours: newest first for a log, oldest first for a plan.

## Tone

Most events are quiet. `accent` lights the one that matters now; `danger` marks one that went wrong. One or two per timeline, or the colour stops meaning anything.

The slot adds something under an event — a button, a badge. It gets the `item`, so you can show it for some events only.

```vue
<OTimeline :items="incident">
  <template #default="{ item }">
    <OButton v-if="item.retry" size="sm" @click="openTrace(item)">Open the trace</OButton>
  </template>
</OTimeline>
```

## Pending

`pending` is an event that has not happened yet: its dot is empty, like a step not taken in [Pips](https://oyna-ui.org/components/pips.md).

```vue
<script setup lang="ts">
const plan = [
  { title: 'Freeze the release branch', time: 'Mon' },
  { title: 'Run the migration on staging', time: 'Tue', tone: 'accent' },
  { title: 'Migrate production', time: 'Thu', pending: true },
  { title: 'Remove the old columns', time: 'next week', pending: true },
]
</script>
```

## Timeline or pips

- **Timeline** — events with names and times, any number of them.
- **[Pips](https://oyna-ui.org/components/pips.md)** — a handful of equal steps with no text of their own.

## Props and slots

| Prop    | Type                                                                                                | Default  | Description |
| ------- | --------------------------------------------------------------------------------------------------- | -------- | ----------- |
| `items` | `{ title: string, time?: string, text?: string, tone?: 'accent' \| 'danger', pending?: boolean }[]` | required |             |

| Slot    | Description                          |
| ------- | ------------------------------------ |
| default | More under an event; gets `{ item }` |

The timeline is a list (`<ol>`), so screen readers announce how many events there are.

Source: https://oyna-ui.org/components/timeline