Alert

Component

Storybook

Figma Demo

Guidelines

Intent

Alerts are intended to notify users of status or an available action. Unlike a dialog, alerts do not require actions.

Variations

Semantic Styling

Alerts are offered in one of four semantic styles based on the type of message being communicated: success, warning, critical, or info.

Type

• Inline alerts: Should be used for alerts that need to persist and remain visible for the user until they are actioned. These alerts fill their parent container, do not have a close control, and may contain CTAs or links.
• Mini alerts: Placed inside existing areas to notify the user of status or an action they should take.
• Overlay alerts: Behave like “toast” notifications. They slide in from the top-center of the screen, have a close control, and are set to time out after 5000ms by default. They may contain CTAs or links.

Iconography

• Semantic alerts: (success, warning, and critical) have a pre-set icon that should not be changed.
• Info alerts: Allow for any icon from our set to be shown.

Usage

Alerts should be used to message users in a non-invasive way. Common use cases for alerts include notification about status (e.g., something was successfully deleted or archived) or an action they should consider (e.g., adding an account number prior to placing an order).

Note that while a critical alert may technically block a user from performing an action, the nature of the alert itself is not as intrusive as a Dialog.

Best Practices

• Basic do/do not guidance.
• Accessibility:
  • Content: Alerts should be short and direct. Leading copy within alerts may be bold, so consider using that treatment for the most important takeaway from the available copy.
  • Actions: Alerts currently allow for either buttons or links, both as single instances or as a pair. Given the intent of alerts and the fact that overlay types may self-dismiss after a few seconds, keep the number of decisions low so that users can scan, action, and get on with their day.

On the code side, the content is handled with an actions slot and does not dictate what should go in it. The content should be built per design specs with Button and Link components.

Component Specs

API

List of all props on the component, their type, default, and description.

Overlay

• open: boolean | Default: true
  Whether the alert should be open.

• overlay: boolean | Default: false
  Whether the alert should be displayed as an overlay. Should be used inside AlertGroup.

• timeout: number | Default: 5000
  The timeout for the alert.

Shared

• class: string | Default: undefined
  Custom class to apply to the component.

• iconName: typeof SvelteComponent | Default: undefined
  The icon to display in the alert.

• title: string | Default: undefined
  The title of the alert.

• testId: string | Default: undefined
  A test id to add to the alert.

• type: 'mini' | Default: undefined
  The type of the alert. Only for inline alerts.

• variant: 'success' | 'warning' | 'critical' | 'info' | Default: 'info'
  The variant of the alert.

• primaryHref: string | Default: undefined
  The href for the primary link.

• primaryId: string | Default: undefined
  The id for the primary link.

• primaryLabel: string | Default: undefined
  The label for the primary link.

• primaryClick: () => void | Default: undefined
  The click handler for the primary link.

• secondaryHref: string | Default: undefined
  The href for the secondary link.

• secondaryId: string | Default: undefined
  The id for the secondary link.

• secondaryLabel: string | Default: undefined
  The label for the secondary link.

• secondaryClick: () => void | Default: undefined
  The click handler for the secondary link.

Example

The example of how to use the components for each variant.

<script>
	import { Alert, AlertGroup } from '@getprovi/craft-svelte';
</script>

<Alert title="The title is bold.">
	Message copy is regular weight. Variant is info by default.
</Alert>
<Alert variant="success" title="Success" />
<Alert variant="warning" title="Warning" />
<Alert variant="critical" title="Critical" />
<Alert type="mini" title="Header copy goes here">Additional context goes here</Alert>
<Alert title="Buttons" primaryLabel="Primary" secondaryLabel="Secondary" />
<Alert
	title="Links"
	primaryLabel="Primary"
	primaryHref="#"
	secondaryLabel="Secondary"
	secondaryHref="#"
/>
<AlertGroup>
	<Alert overlay title="The title is bold." variant="success" on:close={doSomethingOnClose}>
		Message copy is regular weight.
	</Alert>
	<Alert overlay timeout={0} title="No timeout" variant="warning" on:close={doSomethingOnClose}>
		This message will stay until dismissed.
	</Alert>
</AlertGroup>

Types

interface SharedProps {
	class?: string | null | undefined;
	iconName?: typeof SvelteComponent | undefined;
	variant?: 'success' | 'warning' | 'critical' | 'info';
}
interface Mini extends ComponentProps<AlertInline>, SharedProps {
	type: 'mini';
}

interface Overlay extends ComponentProps<AlertOverlay>, SharedProps {
	overlay: boolean;
	open?: boolean;
	timeout?: number;
}

interface Inline extends ComponentProps<AlertInline>, SharedProps {
	open?: never;
	overlay?: never;
	timeout?: never;
	type?: 'default';
}

type Props = Overlay | Inline | Mini;