Toast()

Trigger a tactile moment. Use “toast() to communicate with your users through both sight and touch. It requires a mounted <Toaster /> and import 'web-haptics-toast/dist/styles.css' at your app root.

By default, every toast pulses a haptic pattern on supported devices. If you want to keep a moment quiet, just pass haptics: false.

Rendering the toast

You can call it with just a string.

 
 
`toast`('Hello World!');

Or provide an object as the second argument with more options. They will overwrite the options passed to <Toaster /> if you have provided any.

 
 
`toast`('My toast', {
  className: 'my-classname',
  description: 'My description',
  duration: 5000,
  icon: <MyIcon />,
});

Render toast on page load

To render a toast on initial page load it is required that the function “toast() is called inside of a setTimeout or requestAnimationFrame.

setTimeout(() => {
  `toast`('My toast on a page load');
});

Creating toasts

Success

Renders a checkmark icon in front of the message.

toast.success('My success toast');

Error

Renders an error icon in front of the message.

toast.error('My error toast');

Action

Renders a primary button, clicking it will close the toast and run the callback passed via onClick. You can prevent the toast from closing by calling event.preventDefault() in the onClick callback.

`toast`('My action toast', {
  action: {
    label: 'Action',
    onClick: () => console.log('Action!'),
  },
});

You can also render jsx as your action.

`toast`('My action toast', {
  action: <Button onClick={() => console.log('Action!')}>Action</Button>,
});

Cancel

Renders a secondary button, clicking it will close the toast and run the callback passed via onClick.

`toast`('My cancel toast', {
  cancel: {
    label: 'Cancel',
    onClick: () => console.log('Cancel!'),
  },
});

You can also render jsx in the cancel option.

`toast`('My cancel toast', {
  cancel: <Button onClick={() => console.log('Cancel!')}>Cancel</Button>,
});

Promise

Starts in a loading state and will update automatically after the promise resolves or fails. You can pass a function to the success/error messages to incorporate the result/error of the promise.

toast.promise(myPromise, {
  loading: 'Loading...',
  success: (data) => {
    return `${data.name} toast has been added`;
  },
  error: 'Error',
});

Loading

Renders a toast with a loading spinner. Useful when you want to handle various states yourself instead of using a promise toast.

toast.loading('Loading data');

Custom

You can pass jsx as the first argument instead of a string to render a custom toast while maintaining default styling.

`toast`(<div>A custom toast with default styling</div>, { duration: 5000 });

Headless

Use it to render an unstyled toast with custom jsx while maintaining the functionality. This function receives the Toast as an argument, giving you access to all properties.

toast.custom((t) => (
  <div>
    This is a custom component <button onClick={() => toast.dismiss(t)}>close</button>
  </div>
));

Dynamic Position

You can change the position of the toast dynamically by passing a position prop to the toast function. It will not affect the positioning of other toasts.

// Available positions:
// top-left, top-center, top-right, bottom-left, bottom-center, bottom-right
`toast`('Hello World', {
  position: 'top-center',
});

Other

Updating toasts

You can update a toast by using the toast function and passing it the id of the toast you want to update, the rest stays the same.

const toastId = `toast`('Saving…');
 
toast.success('Saved', {
  id: toastId,
});

On Close Callback

You can pass onDismiss and onAutoClose callbacks to each toast. onDismiss gets fired when either the close button gets clicked or the toast is swiped. onAutoClose fires when the toast disappears automatically after it’s timeout (duration prop).

`toast`('Event has been created', {
  onDismiss: (t) => console.log(`Toast with id ${t.id} has been dismissed`),
  onAutoClose: (t) => console.log(`Toast with id ${t.id} has been closed automatically`),
});

Persisting toasts

If you want a toast to stay on screen forever, you can set the duration to Infinity.

`toast`('This toast will stay on screen forever', {
  duration: Infinity,
});

Dismissing toasts programmatically

To remove a toast programmatically use toast.dismiss(id). The “toast() function return the id of the toast.

const toastId = `toast`('Event has been created');
 
toast.dismiss(toastId);

You can also dismiss all toasts at once by calling toast.dismiss() without an id.

toast.dismiss();

Rendering custom elements

You can render custom elements inside the toast like <a /> or custom components by passing a function instead of a string. This work for both the title and description.

`toast`(
  () => (
    <>
      View{' '}
      <a href="https://google.com" target="_blank" rel="noopener noreferrer">
        Animation on the Web
      </a>
    </>
  ),
  {
    description: () => <button>This is a button element!</button>,
  },
);

Targeting a specific Toaster

You can target a specific Toaster by passing a toasterId option:

// This toast will only appear in the Toaster with id="canvas"
`toast`('This will show in the canvas Toaster', { toasterId: 'canvas' });

API Reference