Toaster

An opinionated toast component for React.

Set up the application root in Getting started.

Code

import { Button, toast } from "@falcon/ui-kit";

export function Example() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        toast("Order has been created", {
          description: "Delivery is scheduled for December 3 at 9:00 AM.",
          action: {
            label: "Undo",
            onClick: () => toast.success("Order creation undone"),
          },
        })
      }
    >
      Show Toast
    </Button>
  );
}

Types

Code

import { Button, toast } from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:flex-wrap tw:gap-2">
      <Button variant="outline" onClick={() => toast("Order has been created")}>
        Default
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.success("Order has been created")}
      >
        Success
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast.info("Pickup is available at the north loading area")
        }
      >
        Info
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.warning("Inventory is below the reorder point")}
      >
        Warning
      </Button>
      <Button
        variant="outline"
        onClick={() => toast.error("Order has not been created")}
      >
        Error
      </Button>
      <Button
        variant="outline"
        onClick={() => {
          toast.promise<{ name: string }>(
            () =>
              new Promise((resolve) =>
                setTimeout(() => resolve({ name: "Order" }), 2000),
              ),
            {
              loading: "Loading...",
              success: (data) => `${data.name} has been created`,
              error: "Error",
            },
          );
        }}
      >
        Promise
      </Button>
    </div>
  );
}

Description

Code

import { Button, toast } from "@falcon/ui-kit";

export function Example() {
  return (
    <Button
      onClick={() =>
        toast("Order has been created", {
          description: "Delivery is scheduled for January 3 at 6:00 PM.",
        })
      }
      variant="outline"
      className="tw:w-fit"
    >
      Show Toast
    </Button>
  );
}

Position

Use the position option to change the position of the toast.

Code

import { Button, toast } from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:h-64 tw:flex-wrap tw:content-center tw:justify-center tw:gap-2">
      <Button
        variant="outline"
        onClick={() =>
          toast("Order has been created", { position: "top-left" })
        }
      >
        Top Left
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast("Order has been created", { position: "top-center" })
        }
      >
        Top Center
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast("Order has been created", { position: "top-right" })
        }
      >
        Top Right
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast("Order has been created", { position: "bottom-left" })
        }
      >
        Bottom Left
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast("Order has been created", { position: "bottom-center" })
        }
      >
        Bottom Center
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast("Order has been created", { position: "bottom-right" })
        }
      >
        Bottom Right
      </Button>
    </div>
  );
}

API

Toaster

Mounts the toast notification region once at the app root. Renders a section element.

Props

className

className?: string

Class name passed to each toast list element.

closeButton

closeButton?: boolean

Whether individual toasts display a close button.

containerAriaLabel

containerAriaLabel?: string

Accessible label for the toast container. Defaults to "Notifications".

dir

dir?: "ltr" | "auto"

Text direction for the toast container. Right-to-left text is not supported.

duration

duration?: number

Default duration, in milliseconds, before a toast closes. Defaults to 4000.

expand

expand?: boolean

Whether stacked toasts expand on hover.

gap

gap?: number

Space, in pixels, between stacked toasts. Defaults to 14.

hotkey

hotkey?: string[]

Keyboard shortcut used to focus the toast container. Defaults to Alt+T.

icons

icons?: ToastIcons

Icons rendered for each toast state. Defaults to Falcon status icons.

id

id?: string

Identifier used to target this toaster.

invert

invert?: boolean

Whether toast colors are inverted.

mobileOffset

mobileOffset?: Offset

Offset applied to toasts on mobile screens. Defaults to 16 pixels.

offset

offset?: Offset

Offset applied to the toast container. Defaults to 24 pixels.

position

position?: Position

Screen position of the toast container. Defaults to "bottom-right".

richColors

richColors?: boolean

Whether toast types use distinct colors.

style

style?: React.CSSProperties

Inline styles passed to each toast list element. Replaces Falcon’s defaults.

swipeDirections

swipeDirections?: SwipeDirection[]

Directions that dismiss a toast with a swipe. Defaults toward its screen edges.

theme

theme?: "light" | "dark" | "system"

Theme used for the toast container. Defaults to "light".

toastOptions

toastOptions?: ToastOptions

Default options applied to every toast. Replaces Falcon’s default toast options.

visibleToasts

visibleToasts?: number

Maximum number of visible toasts. Defaults to 3.