Filtering and controls
Controls for filtering and querying data
Most controls in our products filter what a dashboard, chart or map shows.
Choose a control for the kind of choice it offers, give it a label, and put it next to the content it changes.
Choosing a control
Choose the control by how many options there are and how many the reader can choose.
| The reader chooses | Control |
|---|---|
| One of a few short options, or a view to show | RadioButtonGroupSolid, a row of connected buttons |
| One option from a list | RadioButtonGroup |
| One option from a list too long for radios | Select, with searchable to filter the list by typing |
| Any number of options from a list | CheckboxGroup |
| Any number from a few short options | CheckboxGroupSolid |
| One setting that is on or off | Switch |
| A position in a range of numbers | Input with type="range" |
| A search term | Input |
| A place on a map | MapControlLocationSearch, from @ldn-viz/maps |
| The layers shown on a map | LayerControlGroup |
Some controls are easy to misuse:
- Two or three options need radio buttons, not a select. Radios show every option without a click.
- A slider is for a position, not an exact number. To enter an exact number, a text input is quicker.
- The connected buttons of
RadioButtonGroupSolidrecord a choice. Don't use them for actions.
There is no date picker in the component library. Products use @svelte-plugins/datepicker directly.
A filter panel for a housing dashboard might combine three controls:
<div class="typeset-product flow-compact">
<RadioButtonGroupSolid label="Period" options={periods} bind:selectedId={period} />
<Select label="Borough" options={boroughs} bind:value={borough} searchable clearable />
<CheckboxGroup label="Tenure" options={tenures} bind:selectedOptions={tenure} />
</div>Labels and descriptions
Every control needs a label that says what it filters. Without one, a screen reader announces the control with no name. A description below the control can say more, such as the unit or the source. A hint opens longer help in an overlay, from a small trigger beside the label.
Fields are required unless they're marked optional, and an optional field shows "(optional)" after its label.
Input, Select, CheckboxGroup, CheckboxGroupSolid, RadioButtonGroup, RadioButtonGroupSolid and LayerControlGroup draw their label, description, hint and error message with InputWrapper. Set them with the label, description, hint and error props:
<RadioButtonGroup
label="Measure"
description="Figures are for each financial year."
hint="A financial year runs from April to March."
options={[
{ id: 'count', label: 'Number of homes' },
{ id: 'share', label: 'Share of all homes' }
]}
bind:selectedId={measure}
/>Figures are for each financial year.
A group with no visible label needs ariaLabel, so that a screen reader can name it.
Where controls go
Put a control next to the content it changes:
- Filters for the whole page go in the sidebar. In a dashboard, a filter in the sidebar should apply to every chart on the canvas. Page layout describes the sidebar.
- A filter for one chart goes with the chart.
ChartContainer, from@ldn-viz/charts, has acontrolsslot below the title and above the chart. - Map controls go on the map.
MapControlGrouppositions them, and the location search usually sits in the top-left corner.
A control panel has little space, so set the flow-compact context on it. Flow describes the contexts.
Clearing a choice
Give the reader a way back to the full data:
RadioButtonGroupshows a Clear button above the radios. SetallowCleartofalsewhen one option must always be chosen.CheckboxGrouphas a Select all checkbox, which checks every option that isn't disabled. It's indeterminate when some options are checked.LayerControlGrouphas a Show all checkbox.Selectwithclearablehas a button that clears the value.
In Storybook
Storybook has the props and states of each control, under Ui, Components.