Alerts

Alerts are used to capture the attention of the user in an intrusive way.

installyarn add @clayui/alert
versionNPM Version
useimport Alert, {usePrefersPersistentAlerts} from '@clayui/alert';

Table of Contents

Display Types

The available displayTypes are info, secondary, success, warning, and danger.

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import Alert from '@clayui/alert';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<Alert displayType="info" title="Info" role={null}>
					This is an info message.
				</Alert>

				<Alert displayType="success" title="Success" role={null}>
					This is a success message.
				</Alert>

				<Alert displayType="warning" title="Warning" role={null}>
					This is a warning message.
				</Alert>

				<Alert displayType="danger" title="Danger" role={null}>
					This is a danger message.
				</Alert>
			</div>
		</Provider>
	);
}

We recommend that you review the use cases in the Storybook.

Variants

You can use alert with the feedback, inline, and stripe variants.

Open on CodeSandboxOpen Sandbox
import {Provider, Button} from '@clayui/core';
import Alert from '@clayui/alert';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<div className="c-mt-3">
					<Alert
						actions={
							<Button.Group spaced>
								<Button displayType="warning" small>
									Replace
								</Button>
								<Button alert>Keep Both</Button>
							</Button.Group>
						}
						displayType="warning"
						onClose={() => {}}
						title="Alert"
						variant="inline"
					>
						A file with this name already exists.
					</Alert>
				</div>

				<Alert
					displayType="info"
					title="Info"
					variant="stripe"
					role={null}
				>
					This is a stripe variant.
				</Alert>

				<div className="c-mt-3">
					<Alert
						displayType="success"
						title="This is an inline variant."
						variant="inline"
						role={null}
					/>
				</div>

				<div className="c-mt-3">
					<Alert
						displayType="danger"
						title="This is a feedback variant."
						variant="feedback"
						role={null}
					/>
				</div>
			</div>
		</Provider>
	);
}

Icons

Each Alert displayType has a default icon, the icon can be changed through the symbol attribute.

Open on CodeSandboxOpen Sandbox
import {Provider} from '@clayui/core';
import Alert from '@clayui/alert';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<Alert
					displayType="info"
					symbol="thumbs-up-full"
					title="Info"
					variant="stripe"
					role={null}
				>
					This is a stripe variant.
				</Alert>
			</div>
		</Provider>
	);
}

Using with Button

Open on CodeSandboxOpen Sandbox
import {Provider, Button} from '@clayui/core';
import Alert from '@clayui/alert';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<Alert displayType="info" title="With a Button" role={null}>
					This is an alert with a button!
					<Alert.Footer>
						<Button alert>View</Button>
					</Alert.Footer>
				</Alert>
			</div>
		</Provider>
	);
}

Inline

Open on CodeSandboxOpen Sandbox
import {Provider, Button} from '@clayui/core';
import Alert from '@clayui/alert';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<Alert
					actions={<Button alert>View</Button>}
					displayType="info"
					title="With a Button"
					variant="inline"
					role={null}
				>
					This is an alert with a button!
				</Alert>
			</div>
		</Provider>
	);
}

Using with ToastContainer

You can use alerts with a ToastContainer to render the alerts in a container with position: fixed.

When many toasts are open, they stack. See Stacking.

Open on CodeSandboxOpen Sandbox
import {Provider, Button} from '@clayui/core';
import Alert from '@clayui/alert';
import React, {useState} from 'react';

import '@clayui/css/lib/css/atlas.css';

export default function App() {
	const [toastItems, setToastItems] = useState([]);

	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<div>
					<Button
						onClick={() =>
							setToastItems([...toastItems, Math.random() * 100])
						}
					>
						Add Alert
					</Button>
				</div>

				<Alert.ToastContainer>
					{toastItems.map((value) => (
						<Alert
							autoClose={5000}
							key={value}
							onClose={() => {
								setToastItems((prevItems) =>
									prevItems.filter((item) => item !== value)
								);
							}}
							title="Hola:"
						>
							My value is {value}
						</Alert>
					))}
				</Alert.ToastContainer>
			</div>
		</Provider>
	);
}

Auto Close

Set autoClose to make an alert call onClose on its own. Pass true to close it after 10 seconds, or a number to set the duration in milliseconds.

The countdown waits while the pointer is over the alert or focus is inside it, so users have time to read the alert and use its controls, such as the close button or an action link. Once both the pointer and focus have left, the countdown continues with the remaining time. Moving focus between controls inside the alert, or switching to another window, keeps it waiting.

Alerts stay until they are dismissed when a Provider sets persistentAlerts or document.body has the c-prefers-persistent-alerts class. Either one overrides autoClose. The class applies even when a Provider sets persistentAlerts={false}, and it can be added or removed at any time, so a page can opt in without wiring a Provider. Use them to give users who need more time to read a way to keep alerts open, which helps meet WCAG 2.2.1 (Timing Adjustable). If an alert has no close button (it has no onClose, or it sets hideCloseIcon), give users another way to dismiss it while alerts stay open.

<Provider persistentAlerts spritemap="/public/icons.svg">
	<Alert autoClose={5000} onClose={() => {}} title="Hola:">
		This alert stays until it is dismissed.
	</Alert>
</Provider>

Persistent Alerts in Custom Components

A custom component that closes on its own can follow the same setting with usePrefersPersistentAlerts. It returns true when a Provider sets persistentAlerts or document.body has the c-prefers-persistent-alerts class, and it updates when either one changes. While it returns true, do not start the auto close timer.

Autofocus

Set autoFocus to move focus to an alert when it is shown. The alert focuses itself, so callers do not need to look it up after rendering it.

<Alert autoFocus onClose={() => {}} title="Hola:">
	This alert receives focus when it is shown.
</Alert>

Using with Toaster

ClayToaster shows the toasts of a store inside a ToastContainer. It takes the same props as ToastContainer, plus store. Create the store with createToastStore outside of your components, so any code can add toasts, even code outside of React.

Open on CodeSandboxOpen Sandbox
import {Provider, Button} from '@clayui/core';
import {ClayToaster, createToastStore} from '@clayui/alert';
import React from 'react';

import '@clayui/css/lib/css/atlas.css';

const store = createToastStore();

export default function App() {
	return (
		<Provider spritemap="/public/icons.svg">
			<div className="p-4">
				<Button
					onClick={() =>
						store.add({
							autoClose: 5000,
							children: 'Data is saved',
							displayType: 'success',
							onClose: () => {},
							title: 'Success',
						})
					}
				>
					Add Toast
				</Button>

				<ClayToaster store={store} />
			</div>
		</Provider>
	);
}
  • store.add(props) opens a toast with the given Alert props and returns its key.
  • store.close(key) calls the onClose of the toast, then removes it.
  • store.remove(key) removes the toast without calling onClose .

Stacking

When many toasts are open, the toast container stacks them to save space. The newest toast is always at the bottom and fully visible. Stacking is pure CSS, so it also works with a plain ToastContainer or plain markup:

  • More than 6: the older toasts get narrower, like a pyramid, and sit closer together.
  • More than 12: the older toasts overlap, and only a thin strip of each one shows.
  • More than 20: they overlap more (a thinner strip), and the content of the older toasts is hidden.

Hover or focus a toast to see it in full.

API Reference

Loading API references...Loading API references...Loading API references...Loading API references...Loading API references...Loading API references...
Edit this page on GitHub

Table of Contents