Feedback tones
Error, warning, success and information
Feedback tones carry the meaning of the message through their colour and their default glyph. The tone is always repeated in the title, so colour is never the only signal.
<GlobalBanner tone="error" title="We could not save your details" />
<GlobalBanner tone="warning" title="Your check needs attention" />
<GlobalBanner tone="success" title="Your details are saved" />
<GlobalBanner tone="information" title="Your check is in progress" />AI tone
Suggested by AI
Use the ai tone when the content is generated or suggested by AI. It paints the AI gradient surface. The gradient is light in light mode and dark in dark mode. The glyph and title use the ai ink; the body, action buttons and dismiss use their standard inks.
<GlobalBanner
tone="ai"
title="We found three jobs near you"
body="These suggestions are based on the work you did last month."
/>Neutral tone
No status to report
Use the neutral tone for information that is not a success, warning or error, such as a maintenance notice.
<GlobalBanner
tone="neutral"
title="Scheduled maintenance on Sunday"
body="You will not be able to update your profile between 2am and 4am."
/>Brand tone
A brand-coloured notice
The brand tone uses the feedback brand surface and ink. Brand and neutral take an optional icon; with none, no glyph renders. The other tones own their glyph.
<GlobalBanner
tone="brand"
title="You have a new message from Checkatrade"
body="Open your messages to read it."
/>Bordered
A bottom rule
bordered draws a bottom rule only, so the banner can sit flush against the content below it.
<GlobalBanner
tone="information"
bordered
title="Your check is in progress"
body="We will email you when it is complete."
/>Long copy
Actions beside the copy or below it
There is no layout prop. Actions sit beside the copy when they fit and wrap below it when they do not.
<GlobalBanner
tone="warning"
title="We need to speak to you"
body="We could not finish your right to work check because the document photo was unclear. Request a call back and we will help you complete it over the phone."
primaryAction={{ label: 'Request call back', onClick: requestCallBack }}
secondaryAction={{ label: 'Remind me later', onClick: remindLater }}
onDismiss={dismiss}
dismissLabel="Dismiss banner"
/>When to use
- The message is about the page or the app as a whole, such as a save failure or a scheduled outage.
- It sits at the top of a screen, edge to edge, and the reader needs a strong statement plus up to two Buttons.
Which banner
| Use GlobalBanner when… | Use InPageBanner when… | Use InlineBanner when… |
|---|---|---|
| The message is about the page or the app as a whole. | The message sits in the content next to the thing it is about. | The message is one short line in a dense layout. |
| It sits at the top of a screen, edge to edge. | It sits inside a card, panel or form section. | It sits inside a list row, table cell or form field. |
| The reader needs a strong, unmissable statement plus Buttons. | The reader needs a title, a body and Buttons. | The reader needs one sentence and at most two actions. |
When not to use
- A message beside the thing it is about: use InPageBanner so it sits in the content.
- One short line in a dense layout: use InlineBanner, which has no title.
- A validation error on a single form field: the field’s own error message should carry it.
Layout
GlobalBanner is full width with square corners and at least 44px tall. It lays out one wrapping content row and a dismiss pinned to the top-right corner.
- The glyph sits inline at the start of the title line, top-aligned, with a nudge of half the difference between the title line height and the 24px glyph (1.5px at the base size), so the glyph centres on the first title line.
- When a glyph renders, the content row is indented by the glyph width plus 8px and the glyph is pulled back by the same amount, so the title, the body and any stacked actions all start at the same x. A brand or neutral banner with no glyph has no indent.
- Padding is 20px top and bottom and 24px left. With a dismiss, the right padding reserves the dismiss slot itself; the empty left part of the slot supplies the visible gap. Without one there is no reservation, so the right padding is 24px and the content and actions use the full width.
- The dismiss slot is pinned to the top-right, inset by the padding, plus the same nudge as the glyph. Its 24px circle sits at the slot top-right, so it centres on the first title line and its right edge sits on the padding edge. One exception: when one line of text sits beside a taller button, the row centres that text on the button while the dismiss stays pinned, so the circle sits 7 to 8.5px above the text’s centre (it tracks the responsive title size).
- Each action Button sits in a wrapper that grows from its natural width. Side by side they keep their natural width; once they cannot share a line each wrapped button fills the width.
- The root is top-aligned, with the dismiss pinned to the first line. The content row centres its items on each line: one-line text sits level with a taller button beside it, and a button beside taller text centres on that text.
- The layout adapts on its own. Actions sit beside the copy when they fit and wrap below it when they do not, with a 64px gap beside and a 12px gap when stacked. There is no layout prop.
borderedcolours a bottom rule, so the banner can sit flush against the content below it. Its width is always reserved and its colour is transparent when off, so toggling it never shifts the content or the dismiss.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| tone * | 'error' | 'warning' | 'success' | 'information' | 'ai' | 'brand' | 'neutral' | - | Sets the colours and the glyph. Required: the tone carries meaning, so there is no default. |
| title * | string | - | Rendered as a heading at the level set by titleLevel. |
| body | string | - | Supporting text under the title. An empty string renders nothing. |
| titleLevel | 2 | 3 | 4 | 5 | 6 | 3 | Heading level of the title. |
| icon | ComponentType | IconAsset | - | Only on brand and neutral, where it is optional; with no icon no glyph renders. Not accepted on the fixed-glyph tones. Web: a component from @checkatrade/icons/react. Native: a raw .svg asset from @checkatrade/icons/svg/*. |
| bordered | boolean | false | Draws a bottom border only. |
| primaryAction | { label, onClick } | { label, href, external? } | - | Secondary button. Web: onClick or href, never both. Native: pass { label, onPress }. |
| secondaryAction | Same as primaryAction | - | Tertiary button. Only allowed alongside primaryAction. |
| onDismiss | () => void | - | Shows a dismiss button pinned to the top-right corner. Must be passed with dismissLabel. |
| dismissLabel | string | - | Accessible name for the dismiss button. Required with onDismiss. |
| aria-live | 'off' | 'polite' | 'assertive' | - | Web: passes through to the root. There is no live region by default. To announce a banner shown after an action, keep a live region mounted on a persistent wrapper and render the banner inside it. See the Accessibility tab. |
| accessibilityLiveRegion | 'none' | 'polite' | 'assertive' | - | Native: passes through to the root. It works on Android only, so on iOS call AccessibilityInfo.announceForAccessibility instead. See the Accessibility tab. |
| data-testid | string | - | Web: passed to the root. Parts get '<testid>-title', '<testid>-body' and so on. |
| testID | string | - | Native: passed to the root for test targeting. |
Import
Web
import { GlobalBanner } from '@checkatrade/components-web';Native
import { GlobalBanner } from '@checkatrade/components-native';Basic usage
<GlobalBanner
tone="error"
title="We could not save your details"
body="Check your connection and try again."
primaryAction={{ label: 'Try again', onClick: retry }}
secondaryAction={{ label: 'Contact support', onClick: contact }}
onDismiss={dismiss}
dismissLabel="Dismiss banner"
/> Platform status
| Platform / Area | Status |
|---|---|
| Web (React) | Beta |
| Native (React Native) | Beta |
| iOS (Swift) | Planned |
| Android (Kotlin) | Planned |
| Accessibility audit | Planned |
Accessibility
- There is no live region by default. To announce a banner shown in response to an action, keep a live region mounted on a wrapper that stays on the page and render the banner inside it. On web, put
aria-live="polite"on that wrapper. On native this works on Android only, so on iOS also callAccessibilityInfo.announceForAccessibilitywith the title. Adding a live region together with its content is often not announced. - The title renders as a real heading at
titleLevel. Pick a level that fits the surrounding page. - The icon is decorative and hidden from assistive tech. The tone is carried by the title text, never by colour alone.
- Focus order: actions first, then the dismiss. The title and body are not focusable.
- After
onDismiss, move focus to a sensible element. The component does not manage it.
No releases yet.