London City Data

Feedback and overlays

Messages, tooltips, popovers and modals

Feedback tells the reader what has happened or what is happening. An overlay shows extra content over the page when the reader uses a trigger.

Choose a message by how long it needs to stay and how much of the page it's about. Choose an overlay by how much attention its content needs.

Messages

The messageComponent
Stays on the page, beside the content it's aboutCallout
Confirms an action, or says it failed, for a few secondsToast, from Toaster
Is about the whole page, such as a beta releaseFlag
Takes the place of content that is loading, empty or has failedNonIdealState

Callout

A callout is a coloured banner for a short message that the reader should notice before going on. Its status is notice, positive, caution or negative.

<Callout status="caution">
	{#snippet title()}Provisional figures{/snippet}
	{#snippet body()}The latest quarter will be revised next month.{/snippet}
</Callout>

Say the status in the title. The colour alone doesn't tell every reader what kind of message it is.

Toast

A toast appears for a few seconds after an action, five by default. Use it to confirm that an action worked or to say that it failed. Place one Toaster in the app's layout, then post a message:

import { newToastMessage, ToastType } from '@ldn-viz/ui';
 
newToastMessage('The view was saved.', { type: ToastType.Success, closeButton: true }).post();

The toast's title is its type, such as Success, so write a message that makes sense on its own.

  • Don't put a link or a choice in a toast. It can disappear before a keyboard user reaches it.
  • Don't post a toast for every small change. A screen reader announces each one as an alert.

Flag

A flag is a strip across the top of a page with a status, such as Alpha preview, and an optional link for feedback. A message about one part of a page belongs in a callout beside it.

Loading, empty and failed

When content isn't ready, show the reader that something is happening:

  • LoadingIndicator shows a spinner, or a clock icon when the reader prefers reduced motion. Use it rather than Spinner on its own.
  • NonIdealState fills the space the content will take, with an icon or a spinner, a title and some text. The layout doesn't move when the content arrives.
  • AsyncButton shows a spinner in a button while its action runs.
<NonIdealState spinner>
	{#snippet title()}Loading the map{/snippet}
</NonIdealState>
 
<NonIdealState>
	{#snippet title()}This chart couldn't load{/snippet}
	Refresh the page to try again.
</NonIdealState>
Loading Loading the map
This chart couldn't load
Refresh the page to try again.

Without a title, NonIdealState reads "Nothing to display". On an error, replace it with what failed and what to do next.

Where no text says what is loading, a spinner needs a title for screen readers. LoadingIndicator sets it to "Loading".

Loading

Overlays

An overlay opens from a trigger. The three kinds differ in how they open and how much attention they ask for:

OverlayOpensUse it forElevation
TooltipWhile the trigger is hovered or focusedA short hint that needs no interaction4
PopoverOn a click, and stays open until closedHelp to read at the reader's own pace, or to interact with4
ModalOn a click, and blocks the page behind itA task or message that needs full attention5

Overlay renders any of the three, chosen by its overlayType. Each has a default trigger: a small text button with an information icon, labelled by hintLabel. A trigger snippet replaces it with your own element.

<Tooltip hintLabel="What is a completion?">
	A home counts as complete when it's ready to live in.
</Tooltip>
 
<Popover hintLabel="About this data">
	{#snippet title()}About this data{/snippet}
	Figures come from borough returns. <a href="#">Read the method</a>.
</Popover>
 
<Modal bind:open>
	{#snippet trigger(props)}
		<Button {...props}>Delete view</Button>
	{/snippet}
	{#snippet title()}Delete this view?{/snippet}
	{#snippet description()}The view and its filters will be removed.{/snippet}
	{#snippet buttons()}
		<Button variant="outline" emphasis="secondary" onclick={() => (open = false)}>Cancel</Button>
		<Button emphasis="negative" onclick={() => (open = false)}>Delete</Button>
	{/snippet}
</Modal>

Some content suits one overlay and not another:

  • Don't put a link or a button in a tooltip. It closes as the pointer moves towards it, so nobody can reach the link. Use a popover.
  • Don't use a popover for something the reader must answer before going on. A modal blocks the page behind it.
  • Give a modal a title. A screen reader uses it as the dialog's name.

A modal keeps focus inside it until it closes, and Escape or the close button closes it. The page behind is dimmed and doesn't scroll.

In Storybook

Storybook has the props and states of each component, under Ui, Components.