---
title: "Options on a setting"
description: "Every kind takes one options object, every key optional, and a key the kind cannot use is refused by name, on the declaration's line."
order: 24
section: "settings"
---

<!-- source: docs/indicators/settings/options.md; generated by packages/cli/scripts/gen-indicator-docs.ts, do not edit -->

# Options on a setting

Every kind takes one options object, every key optional, and a key the kind cannot use is refused by name, on the declaration's line.

## What it is

An option is one of the dialog's words on a declaration: the row's name,
its stepper, a glyph with a tooltip, which rows share a line, which
toggle dims it, where it lands, and the bounds of a number field. Plain
`param(...)` keeps its four keys, `required`, `min`, `max` and
`description`; the dialog's words belong to the typed settings,
`param.int(...)`, `param.bool(...)` and the rest.

## Declare it

```typescript
// Two fields on one line of the dialog, the first with a hint.
param.int("fast", 9, { min: 1, max: 200, row: "lengths", hint: "Bars in the fast average" });
param.int("slow", 21, { min: 2, max: 400, row: "lengths" });
param.color("slow_color", "#f59e0b", { label: "Color" });
param.bool("smooth", false);
// Dimmed until the toggle it names is on.
param.number("smoothing", 0.3, { min: 0, max: 1, step: 0.05, slider: true, when: "smooth" });
```

| Option | What it does |
| --- | --- |
| `label` | the row's name in the dialog. Without one the row shows `description`, else the name read as words (`show_bands` reads "Show Bands") |
| `description` | the long text of the setting, recorded in the sheet |
| `min`, `max` | bounds of a number field: a setting outside them is refused by name before the module runs; required by `slider` and by `param.range`; on `param.list`, `max` is the most items the list may hold |
| `step` | the stepper's increment and, on `int`, `number` and `range`, the grid a setting sits on, counted from `min` (or 0 without one): a value off it is refused by name before the module runs. A `param.int` steps by 1 unless you say otherwise; on `price`, `step` is the stepper alone |
| `slider` | `true` draws a bounded `param.int` or `param.number` as a slider |
| `hint` | words behind a small glyph after the label, shown on hover |
| `row` | rows that name the same word share one line of the dialog |
| `when` | the NAME of a `param.bool`: the row is dimmed while that toggle is off |
| `hide` | with `when`: hide the row instead of dimming it |
| `group` | `"Page"` or `"Page/Section"`: where the row lands, shorthand for the layout words ([Pages, sections, dividers, notes](layout.md)) |
| `unit`, `unit_default` | a unit picker beside a number ([Sessions and units](sessions-and-units.md)) |
| `confirm` | marks a setting whose change is worth confirming before it applies (one that refetches); recorded in the sheet, and the dialog applies edits as you make them for now |
| `required` | recorded in the sheet; on the chart a setting always has a value |
| `tz` | `param.session` only: the zone the window is written in |

## Which kind takes which option

| Option | Kinds that take it |
| --- | --- |
| `label`, `description`, `group`, `row`, `hint`, `when`, `hide`, `confirm`, `required` | every typed kind |
| `min`, `max`, `step`, `slider` | the number fields: `int`, `number`, `price`, `range` |
| `max` | also `param.list`, as the most items the list may hold |
| `unit`, `unit_default` | one number field: `int`, `number`, `price` (a range's two ends have no unit picker) |
| `tz` | `param.session` only |
| `required`, `min`, `max`, `description` | plain `param`, which takes no other key |

On any other kind they are refused.

## What the dialog draws

![a toggle and a timeframe menu sharing one line of the dialog](/wrun/images/wrun-settings-bool-row.svg)

![the hint glyph after a label, with its words shown on hover](/wrun/images/wrun-layout-hint.svg)

![a bounded whole number drawn as a slider with its readout](/wrun/images/wrun-settings-slider.svg)

The dialog adds the rest by itself. A row that differs from its default
shows a dot and a reset button that names the default, and a dialog with
more than twelve settings gets a filter box over every page.

## Gotchas

- `when` on a setting takes the NAME of a `param.bool`; `toggle` and
  `when` on a `section(...)` take the toggle's HANDLE
  ([Pages, sections, dividers, notes](layout.md)).
- A key the kind does not take: `param.int options accept only { required,
  min, max, description, label, step, group, row, hint, when, hide,
  slider, unit, unit_default, confirm }, not 'tooltip'`.
- A typed key on plain `param`: `param options accept only { required,
  min, max, description }, not 'label'`.
- A number-field key on a toggle: `param.bool 'x' takes no min option
  (its value is not a number field)`.
- A unit picker on a range: `param.range 'r' takes no unit option (a unit
  picker sits beside one number field, not a range)`.
- `hide` without `when`: `param.int 'x' declares hide without when; hide
  names what happens when the when param is off, so declare when beside
  it`.
- `when` naming a setting that is not a toggle: `param.int 'x' when names
  'y', which is not a param.bool (when takes the NAME of a param.bool,
  e.g. when: "show_bands")`.
- A slider without both bounds: `param.int 'x' declares slider without
  min and max (a slider needs both bounds)`.

## Related

- [Setting kinds](kinds.md): the fifteen kinds the options sit on
- [Pages, sections, dividers, notes](layout.md): `group` written out as layout words
- [Sessions and units](sessions-and-units.md): `unit`, `unit_default` and `tz` in full
- [What the build checks](checks.md): the refusal table