A non-disruptive message that appears at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action. Snackbars communicate messages that are minimally interruptive.

Importing

Typically, you'll invoke snackbars via the included snackbars context.

A useSnackbars hook is available as:

import { useSnackbars } from '@customerio/pluma-components/react';

In case you need to render a snackbar directly, the component can be imported:

import { Snackbar } from '@customerio/pluma-components/react';

Usage

The useSnackbars react hook returns the snackbars context, which includes a create function.

create accepts an object with the following keys:

message: the text to display in the snackbar. This is required.
id: a unique string id of the snackbar (used to prevent showing the same snackbar multiple times). If none is provided, a random id will be generated.
action: an action definition (see below).
layout: the layout of the snackbar.
variant: the visual variant of the snackbar (default, error, or success).
isError: whether the snackbar should be rendered in the error state (deprecated, use variant="error" instead).
shouldCloseOnAction: whether the snackbar should close when the action button is clicked.
autoCloseTimeout: how long to wait until the snackbar closes automatically (in milliseconds). If the snackbar has an action, the timeout will be doubled. Defaults to 5000.
animationTransitionDuration: the duration of the CSS enter/exit animation. Defaults to 150 (in ms).
offset: an offset definition (see below).

Calling create will render a snackbar at the bottom of the screen. By default, a snackbar will automatically close after 5 seconds (or 10 seconds if it has an action).

import { Button, ButtonGroup, useSnackbars } from '@customerio/pluma-components/react';

export default function Example() {
	const snackbars = useSnackbars();
	
	const handleDefaultClick = () => {
		snackbars.create({
			message: 'This is a default snackbar message',
		});
	};
	
	const handleSuccessClick = () => {
		snackbars.create({
			message: 'Operation completed successfully!',
			variant: 'success',
		});
	};
	
	const handleErrorClick = () => {
		snackbars.create({
			message: 'An error occurred',
			variant: 'error',
		});
	};
	
	return (
		<ButtonGroup groupVariant="spaced">
			<Button onClick={handleDefaultClick}>Default Snackbar</Button>
			<Button onClick={handleSuccessClick}>Success Snackbar</Button>
			<Button onClick={handleErrorClick}>Error Snackbar</Button>
		</ButtonGroup>
	);
}

SnackbarApi

Internally, useSnackbars creates an instance of a SnackbarApi class, which manages the current state and exposes the create/destroy methods. It is possible to pass in your own instance of this class, by either configuring it in the PlumaProvider's global config (below).

This is useful in situations where we want to pass around that API instance outside of the render context of a component. useSnackbars relies on context providers, and because of this can't be used in functional utilities or Ember services.

Pluma exports the class, and it can be imported and used as demonstrated below:

import { PlumaSnackbarApi } from '@customerio/pluma-components/react';

export const snackbarApi = new PlumaSnackbarApi();

return App = ({children}) => <PlumaProvider
	componentConfig={{
		PlumaSnackbar: {
			snackbarApi: snackbarApi,
		}
	}}
>
	{children}
</PlumaProvider>;

`PlumaProvider` configuration

By default, a snackbar invoked like demonstrated above will disappear after 5 seconds (or 10 seconds if it has an action). Additionally, it will animate in and out with a CSS opacity and translate transition, with a duration of 150ms.

These value can be customized on individual snackbars in the create context function. Additionally, they can globally configured on the PlumaProvider component. PlumaProvider accepts a componentConfig prop, which accepts a PlumaSnackbar key to override the defaults:

<PlumaProvider
	componentConfig={{
		PlumaSnackbar: {
			autoCloseTimeout: 2000,
			animationTransitionDuration: 500,
		}
	}}
>
	{children}
</PlumaProvider>

For example:

Anatomy of the Snackbar

By default, a snackbar is a short piece of text with a close button. You can make it more dynamic, however, by adding an action the user can take and allowing for more whitespace within the snackbar.

Note: The close button is only rendered when an onClose callback is provided.

Layout

The layout of the snackbar determines the positioning of the three elements: text, close button, and action button.

Condensed: The smallest version of a snackbar. This is the default layout, and makes all three elements inline with each other. Here the action is optional, and the snackbar can simply be a piece of text and the close button