Foundations
Choosing a control
Every control on a page comes from the kit, and each kind of question has one control that answers it. Choosing by the question, not by what looks right on the day, is what makes two screens built months apart feel like one product.
The rule
| The reader is asked to | Use | Note |
|---|---|---|
| Do something | Button | One primary per surface. A link that should look like a button is a Button with href. |
| Turn a setting on or off, effective at once | Toggle | It saves the moment it moves, so it carries no Save button. |
| Agree to one thing inside a form saved later | Checkbox | A terms box, an opt-in. |
| Pick several of a short set | CheckboxGroup | Every option on screen. |
| Pick several of a long or loaded set | MultiSelect | Rows from data, or more than about seven. |
| Pick one of two to four short options | SegmentedControl | A period, a mode, a method, a filter. Every option is visible and one is always chosen. |
| Pick one of many short options, all in sight | FilterChips | A filter over a dozen categories, or a demo that shows every option. The chips wrap. |
| Pick one of a few options that each need a sentence | RadioGroup | Give each option a description. The reader compares them before choosing. |
| Pick one of five or more, or of rows from data | Select | Add searchable past about ten rows. |
| Find one of many by typing | Autocomplete | Typing is the main way in. |
| Type text | Input, Textarea | PasswordInput for a secret, SearchInput for a query, NumberInput for a number. |
| Enter a date or a time | DatePicker, TimePicker, DateTimePicker | Never the browser picker. |
| Pick a color | ColorField | A typed hex, or swatches from the theme. Never the browser picker. |
| Put rows in order | SortableList | A drag, the handle menu, or Alt with an arrow, and every move is announced. |
| Attach a file | FileInput | The only control that opens the system file dialog, which is the point. |
Count "All" or "Anyone" in a filter as an option. A status filter of All, Open and Closed is three options and a SegmentedControl. All beside four statuses is five, and a Select.
Never the browser's own control
A native select, date field, color field, range slider, checkbox or radio is drawn by the browser
and the operating system, in their font, colors and highlight. No theme reaches it. A native
select's list opens white on a dark page, in the middle of a checkout. The kit draws its own
select, date and time fields, checkbox and radio, so a page never writes <select>, <option> or an <input> whose type a kit component covers. Hidden
inputs, which render nothing, are the exception.
A color is a ColorField, which takes typed hex or a swatch from the theme. The kit ships no range slider. A page that needs one adopts a control that draws itself and wraps it in Field, which gives it the label and the message row every kit control carries. It never falls back to the browser's.
The same holds for a button. A hand-styled element that repaints a Button variant is a second button style a few pixels off the first. Use the variant.
A single choice always shows its value
A SegmentedControl, RadioGroup or Select that has a value draws it. A group must never render with nothing selected while its form posts a default, because the screen and the request then disagree until somebody clicks. Start with the value the form will post, or with a placeholder that posts nothing.
Saving on change
A Select and a SegmentedControl post through a hidden input that is written on the next update. A
Select's onvaluechange already fires after it. A SegmentedControl's onchange fires before it, so wait a tick() before requestSubmit(), or the form posts the value it held before the change. The SegmentedControl page shows the pattern.
Two choices side by side
Short choices sit in one row and read as a sentence: how often, and how.
Options that need explaining
A longer list
On, off, and agree
A Toggle changes something now. A Checkbox records an answer that the form sends later. If a setting needs a Save button, it is a Checkbox.