Toast notification
Event-driven, real-time notifications that provide additional information to the user.
Overview
Resources
Install
yarn add @activecampaign/camp-components-toastVariations
Banners can be static (static banners) or event-driven (toast notifications).
ActiveCampaign’s toast notifications are event-driven, real-time notifications that provide additional information to the user. They typically auto-expire (enter and exit based on a time limit specified by the designer) and can optionally include actions for the user to take.
Appearance
All banner appearances are available for toast notifications.
createToast({
title: 'Changes saved successfully',
appearance: 'success',
});Actions
Additional actions can be provided to the toast notification, just like a banner. When adding actions, you might consider overriding or changing the dismiss behavior. Learn more about that below.
createToast({
appearance: 'destructive',
title: 'An error occured when saving',
actions: () => <Button.Outline size="small">Try again</Button.Outline>;
});Duration
Provide a duration and the notification will self dismiss after a period of time. You can provide one of the default durations or a custom duration as a number of milliseconds.
The default values available are:
- “short” – for quick and very short messages like “Saved”, “Success”, etc. that are helpful but not vital.
- “standard” – for messages with slightly longer messages that are helpful but not vital.
- “long” – for messages with more text that are helpful and considered somewhat important to read.
If the message is vital to read, do not provide a duration and allow the user to manually dismiss only.
createToast({
title: 'Success',
appearance: 'success',
duration: 'short',
});Implementation details
Creating a toast notification
Before creating toasts, your application must have a <Toaster> component to post the toasts to (this already exists in the orchestration and Ember app).
Toast notifications can be created from anywhere using the createToast() function and passing in properties related to the Banner that will be rendered.
Note: The createToast() and destroyToast() methods are not specific to React and may be called from any javascript environment (including Ember), however, notifications are rendered using the toast notification component, which is in React. Learn more below.
By default, the banner you create will come with its own dismiss handler, so you don’t need to provide properties related to that unless you want to manually control that behavior.
import { createToast } from '@activecampaign/camp-components-toast';
const MyComponent = () => {
const notify = () => {
createToast({
title: 'Toaster Banner Title',
description: 'This is a Toast notification, and it accepts all the same props as Banner.',
});
};
return <Button onClick={notify}>Create Toast</Button>;
};Controlling dismiss behavior
Calling destory toast
When createToast() is called, it returns the ID for the newly created notification. If you store this ID, you can call destroyToast() and provide the ID to manually dismiss it.
import { createToast, destroyToast } from '@activecampaign/camp-components-toast';
const toastId = createToast({
title: 'Change saved',
actions: () => <Button onClick={undo}>Undo</Button>,
});
const undo = () => {
// Code to undo last action, then we can destroy the toast manually.
destroyToast(toastId);
};Overriding the dismiss button
The onDismiss function for the notification is handled by default, but you’re free to override. In the context of a Toast notification, onDismiss will provide the toast ID when called.
When doing this, you’ll also need to provide your own translated dismissLabel as well.
import { createToast, destroyToast } from '@activecampaign/camp-components-toast';
createToast({
title: 'My Notification',
onDismiss: handleDismiss,
dismissLabel: 'Dismiss',
});
const handleDismiss = (id) => {
// do stuff then destroy the toast notification
destroyToast(id);
};Hiding the dismiss button
If you want to remove the dismiss button from a notification completely, simply override the onDismiss function with null.
createToast({
title: 'Notification with no dismiss button',
onDismiss: null,
});Render notifications with Toaster
The <Toaster /> component is what renders the notifications in the UI. There must only be one toast notification in the platform, otherwise, each notification will be rendered more than once. So generally, you won’t have to ever use this component.
There may be scenarios where you want to render notifications in a sandbox environment, in which case you may need to implement the toast notification, just make sure it’s contained by a sandbox that will never be rendered in the main platform.
import { Toaster } from '@activecampaign/camp-components-toast';
import MyComponent from './src';
const MySandboxEnvironment = () => {
return (
<div>
<MyComponent />
<Toaster toastDismissButtonLabel="Dismiss" />
</div>
);
};Usage
Best practices
- A maximum of 2 actions can be placed in the toast notification, although it is recommended to keep it consolidated to a single action to narrow focus of the toast notification’s purpose. Rather than any “dismiss”-type button actions, use the dismiss indicator in the corner instead.
Content guidelines
Toast notificaition titles are written clearly in sentence case and in complete sentences, with no punctuation at the end. Write toast notification titles so that they can be easily translated into different languages. Toast notification descriptions should be written in full and complete sentences, with punctuation at the end.
Accessibility
Keyboard support
- When there is a dismiss indicator, move focus to it using the
tabkey - When there are actions, move focus to them using the
tabkey - On either the dismiss indicator or actions, use the
spaceorenterkey to perform action
