Shared options
Themes, number format, min, max and step, and forms work the same in every kit component that has them.
Themes
Put theme="dark", "light" or "glass" on a component, or the class ok-theme-dark, ok-theme-light or ok-theme-glass on a container. Everything inside follows, so one class themes a whole dashboard.
- A theme is a set of the
--ok-*custom properties, inside:where(). It has zero specificity, so any rule of yours wins, and color attributes likefillwin too. - Custom properties inherit, so the closest theme wins: a
theme="light"gauge inside anok-theme-darkpanel is light. - Without a theme, components keep their own defaults.
- Glass makes faces and panels translucent and blurs what is behind them (
backdrop-filter). It wants a colorful or photographic background.
The properties a theme sets, and what reads them:
| Property | What it colors |
|---|---|
--ok-fill, --ok-track | Value arcs and their tracks. |
--ok-accent | Needles, second hands, compass index, menu highlight. |
--ok-text | Readouts, numerals and labels. |
--ok-face, --ok-bezel, --ok-case | Dials, their rims and the case around them. |
--ok-tick, --ok-hand | Minor ticks; hands, major ticks and strong numbers. |
--ok-surface | Panels such as the menu hub and the needle cap. |
--ok-focus | Focus rings. |
--ok-backdrop | The backdrop-filter of faces and panels. Set by glass. |
To tweak a theme, set a property next to it:
.dashboard { --ok-fill: #ffb547; } /* beats the theme */
<div class="dashboard ok-theme-dark"> … </div>The menu already had a theme attribute for its sector colors. That is now palette="mono|color"; theme="color" still works and combines with the others, as in theme="color light".
Number format
format picks how numbers are written, through Intl.NumberFormat. It reaches the readout, the tick labels and aria-valuetext.
| Attribute | What it does |
|---|---|
format | decimal, percent, currency, unit or compact (1.2K, 3.4M). |
decimals | Digits after the decimal point, fixed. Without it, each format uses its usual number. |
currency | ISO code for format="currency", USD by default. Setting it alone implies the currency format. |
unit | Text after the number, as before (unit="%"). With format="unit" it names an Intl unit instead: kilometer-per-hour, celsius, megabyte. |
locale | A language tag like de-DE. Without it, the closest lang attribute, then the browser's language. |
percent shows where the value sits between min and max: 50 on a 0 to 200 gauge reads 25%. In a donut it is the share of the total. Without any of these attributes, numbers look the way they did in 1.0. A bad currency or unit never breaks the component: it falls back to a plain number.
A formatter for full control
Set formatter to a function and it writes every number. The second argument says where the number goes: kind is value, tick or aria, and you get min, max and locale. Its text is used as is, without the unit.
min, max and step
Every component with a value reads min, max and step the way <input type="range"> does.
- Values are clamped to the range, readouts included. A
maxbelowminbecomesmin. stepsnaps values to a grid that starts atmin. Both ends stay reachable, even when the step does not divide the range.step="any"turns snapping off.- Display components (gauge, meter, instrument) do not snap unless you give them a
step. The knob steps by 1. - Keys: arrows move one step, Page Up and Page Down ten, Home and End go to the ends. Without a step they move 1% of the range.
aria-valuemin,aria-valuemax,aria-valuenowandaria-valuetextfollow, the last one through the number format.
Rings read min and max as defaults for each ring, and a ring in data can set its own. The radar reads dist between them, so blips can be in kilometers. On the rings, step was already the space between rings; it keeps that meaning, and spacing is its new name.
Forms
<o-knob> and <o-menu> are form controls. Give them a name and they submit with their form like an <input>.
| Name | What it does |
|---|---|
name | The field name in the form data. Without it, nothing is sent. |
value | The attribute is the default value: the control starts there and a form reset goes back to it. The property is the current value; setting it fires no event. |
disabled | Out of the tab order, ignores input and is not sent. A disabled <fieldset> does the same. :disabled works in CSS. |
required | Menu only: the form does not submit until an item is picked. A knob always has a value. |
input, change | Events, as on native inputs: input on every change by the user, change when a gesture ends, on each key press, and on each menu pick. event.detail.value has the value. |
form, labels, validity, checkValidity(), reportValidity() | The same as on an <input>. A <label for> names the control. |
The menu submits the value of the picked item, as JSON when it is an object. Pages restored with the back button come back with the values they had.
Which component takes what
| Component | Theme | Format | min / max / step | Form |
|---|---|---|---|---|
| Gauge | yes | readout | all three | |
| Knob | yes | readout | all three, keys | yes |
| Menu | yes | yes | ||
| Instrument | yes | readout, scale | all three | |
| Donut | yes | segments | ||
| Rings | yes | rings | min, max | |
| Compass | yes | heading | ||
| Radar | yes | distances | min, max | |
| Radar chart | yes | tooltip, scale, table | min, max, also per axis | |
| Spinner | yes | progress readout | min, max | |
| Sunburst | yes | values, middle | ||
| Range | yes | readout | all three, keys | yes |
| Time picker | yes | min, max (times) | yes | |
| Color wheel | yes | yes | ||
| Wheel | yes | |||
| Clock, Timer, Status | yes |
<o-meter> takes the same as the instrument. Clocks and timers show times, not numbers, so they have no number format.