React-Bootstrap-Toasts

Dynamically create react-bootstrap toasts via a simple api.

Live demo

https://jukanntenn.github.io/react-bootstrap-toasts/

Installation

# npm
npm install react-bootstrap-toasts

# yarn
yarn add react-bootstrap-toasts

# pnpm
pnpm add react-bootstrap-toasts

Basic Usage

1: Wrap your app inside a ToastsProvider component:

1import { ToastsProvider as BootstrapToastsProvider } from 'react-bootstrap-toasts';
2
3<BootstrapToastsProvider>
4  <App />
5</BootstrapToastsProvider>;

2: Use useToasts hook:

1import { Button } from 'react-bootstrap';
2import { useToasts } from 'react-bootstrap-toasts';
3
4function App() {
5  const toasts = useToasts();
6
7  return (
8    <Button
9      onClick={() => {
10        toasts.show({
11          headerContent: 'Bootstrap',
12          bodyContent: 'Toast body content.',
13          toastProps: {
14            bg: 'primary',
15          },
16        });
17      }}
18    >
19      Show toast
20    </Button>
21  );
22}

Toast Options

toasts.show method accepts a toastOptions argument to control behavior of the created toast. Here is toastOptions type definition:

1type ToastOptions<T extends ToastProps> = {
2  headerContent: string | JSX.Element;
3  bodyContent: string | JSX.Element;
4  toastProps?: T;
5  toastHeaderProps?: ToastHeaderProps;
6  toastBodyProps?: BsPrefixProps & HTMLAttributes<ElementType>;
7};

headerContent: Child elements of react-bootstrap Toast.Header component.

bodyContent: Child elements of react-bootstrap Toast.Body component.

toastProps: A ToastProps object which will be passed down to react-bootstrap Toast component.

toastHeaderProps: A ToastHeaderProps object which will be passed down to react-bootstrap Toast.Header component.

toastBodyProps: A object which will be passed down to react-bootstrap Toast.Body component.

For example, to create an autohide toast with contextual danger variation:

1import { Button } from 'react-bootstrap';
2import { useToasts } from 'react-bootstrap-toasts';
3
4function App() {
5  const toasts = useToasts();
6
7  return (
8    <Button
9      onClick={() => {
10        toasts.show({
11          headerContent: <span className="me-auto">Bootstrap</span>,
12          bodyContent: 'Toast body content.',
13          toastProps: {
14            bg: 'danger',
15            autohide: true,
16            delay: 3000,
17          },
18        });
19      }}
20    >
21      Show toast
22    </Button>
23  );
24}

For more details, please check react-bootstrap toasts API.

Toast Container Props

ToastsProvider accepts a toastContainerProps prop, which is a ToastContainerProps object that will be passed down to react-boostrap ToastContainer component.

Usually you want this to control the position where toasts to place or apply additional css style to the toast container.

The example below shows how to set all toasts should be placed at top-end of the viewport and also set the toast container's padding:

1import { ToastsProvider as BootstrapToastsProvider } from 'react-bootstrap-toasts';
2
3<BootstrapToastsProvider toastContainerProps={{ position: 'top-end', className: 'p-2' }}>
4  <App />
5</BootstrapToastsProvider>;

Limit number of toasts

The default number of toasts displayed is infinite. You can set limit to control maximum number of toasts displayed on screen. If number of toasts exceeds this value, oldest toast would be removed.

1import { ToastsProvider as BootstrapToastsProvider } from 'react-bootstrap-toasts';
2
3<BootstrapToastsProvider limit={3}>
4  <App />
5</BootstrapToastsProvider>;

Hide Toast

The toasts.show method returns an id of the created toast which can be used to hide the toast manually via toasts.hide method:

1import { useState } from 'react';
2import { Button } from 'react-bootstrap';
3import type { ToastIdType } from 'react-bootstrap-toasts';
4import { useToasts } from 'react-bootstrap-toasts';
5
6function App() {
7  const toasts = useToasts();
8  const [toastId, setToastId] = useState<ToastIdType | undefined>();
9  {
10    toastId === undefined ? (
11      <Button
12        className="me-3"
13        onClick={() => {
14          const id = toasts.show({
15            headerContent: <span className="me-auto">Bootstrap</span>,
16            bodyContent: 'Toast body content.',
17          });
18          setToastId(id);
19        }}
20      >
21        Show toast
22      </Button>
23    ) : (
24      <Button
25        variant="danger"
26        onClick={() => {
27          toasts.hide(toastId);
28          setToastId(undefined);
29        }}
30      >
31        Hide toast
32      </Button>
33    );
34  }
35}

Shotcut methods

react-bootstrap provides some contextual variations of toasts. react-bootstrap-toasts provides a corresponding shortcut method for each contextual variation. For example:

1const toasts = useToasts();
2
3// create a contextual warning toast
4toasts.warning({
5  headerContent: <span className="me-auto">Bootstrap</span>,
6  bodyContent: 'Toast body content.',
7});
8
9// is equivalent to
10toasts.show({
11  headerContent: <span className="me-auto">Bootstrap</span>,
12  bodyContent: 'Toast body content.',
13  toastBodyProps: {
14    bg: 'warning',
15  },
16});

All available shortcut methods:

1toasts.info(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;
2
3toasts.primary(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;
4
5toasts.secondary(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;
6
7toasts.success(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;
8
9toasts.danger(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;
10
11toasts.warning(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;
12
13toasts.dark(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;
14
15toasts.light(toastOptions: ToastOptions<ToastPropsOmitBg>): ToastIdType;

TODO

• Improving documentation.
• Smoother animation of toast transition.