Toast

Import

import { Toast, useToast } from 'heroui-native';

Anatomy

<Toast>
  <Toast.Title>...</Toast.Title>
  <Toast.Description>...</Toast.Description>
  <Toast.Action>...</Toast.Action>
  <Toast.Close />
</Toast>

• Toast: Main container that displays notification messages. Handles positioning, animations, and swipe gestures.
• Toast.Title: Title text of the toast notification. Inherits variant styling from parent Toast context.
• Toast.Description: Descriptive text content displayed below the title.
• Toast.Action: Action button within the toast. Button variant is automatically determined based on toast variant but can be overridden.
• Toast.Close: Close button for dismissing the toast. Renders as an icon-only button that calls hide when pressed.

Usage

Usage Pattern 1: Simple String

Show a toast with a simple string message.

const { toast } = useToast();

toast.show('This is a toast message');

Usage Pattern 2: Config Object

Show a toast with label, description, variant, and action button using a config object.

const { toast } = useToast();

toast.show({
  variant: 'success',
  label: 'You have upgraded your plan',
  description: 'You can continue using HeroUI Chat',
  icon: <Icon name="check" />,
  actionLabel: 'Close',
  onActionPress: ({ hide }) => hide(),
});

Usage Pattern 3: Custom Component

Show a toast with a fully custom component for complete control over styling and layout.

const { toast } = useToast();

toast.show({
  component: (props) => (
    <Toast variant="accent" placement="top" {...props}>
      <Toast.Title>Custom Toast</Toast.Title>
      <Toast.Description>This is a custom toast component</Toast.Description>
      <Toast.Close />
    </Toast>
  ),
});

Note: Toast items are memoized for performance. If you need to pass external state (like loading state) to a custom toast component, it will not update automatically. Use shared state techniques instead, such as React Context, state management libraries, or refs to ensure state updates propagate to the toast component.

Disabling All Animations

Disable all animations including children by using "disable-all". This cascades down to all child components (like Button in Toast.Action).

const { toast } = useToast();

toast.show({
  variant: 'success',
  label: 'Operation completed',
  description: 'All animations are disabled',
  animation: 'disable-all',
});

Or with a custom component:

const { toast } = useToast();

toast.show({
  component: (props) => (
    <Toast variant="accent" animation="disable-all" {...props}>
      <Toast.Title>No animations</Toast.Title>
      <Toast.Description>
        This toast has all animations disabled
      </Toast.Description>
      <Toast.Action>Action</Toast.Action>
    </Toast>
  ),
});

Example

import { Button, Toast, useToast, useThemeColor } from 'heroui-native';
import { View } from 'react-native';

export default function ToastExample() {
  const { toast } = useToast();
  const themeColorForeground = useThemeColor('foreground');

  return (
    <View className="gap-4 p-4">
      <Button
        onPress={() =>
          toast.show({
            variant: 'success',
            label: 'You have upgraded your plan',
            description: 'You can continue using HeroUI Chat',
            actionLabel: 'Close',
            onActionPress: ({ hide }) => hide(),
          })
        }
      >
        Show Success Toast
      </Button>

      <Button
        onPress={() =>
          toast.show({
            component: (props) => (
              <Toast variant="accent" {...props}>
                <Toast.Title>Custom Toast</Toast.Title>
                <Toast.Description>
                  This uses a custom component
                </Toast.Description>
                <Toast.Action onPress={() => props.hide()}>Undo</Toast.Action>
                <Toast.Close className="absolute top-0 right-0" />
              </Toast>
            ),
          })
        }
      >
        Show Custom Toast
      </Button>
    </View>
  );
}

Global Configuration

Configure toast behavior globally using HeroUINativeProvider config prop. Global configs serve as defaults for all toasts unless overridden locally.

Note: For complete provider configuration options, see the Provider documentation.

Insets

Insets control the distance of toast sides from screen edges. Insets are added to safe area insets. To set all toasts to have a side distance of 20px from screen edges, configure insets:

<HeroUINativeProvider
  config={{
    toast: {
      insets: {
        top: 20,
        bottom: 20,
        left: 20,
        right: 20,
      },
    },
  }}
>
  {children}
</HeroUINativeProvider>

Content Wrapper with KeyboardAvoidingView

Wrap toast content with KeyboardAvoidingView to ensure toasts adjust when the keyboard appears:

import {
  KeyboardAvoidingView,
  KeyboardProvider,
} from 'react-native-keyboard-controller';
import { HeroUINativeProvider } from 'heroui-native';
import { useCallback } from 'react';

function AppContent() {
  const contentWrapper = useCallback(
    (children: React.ReactNode) => (
      <KeyboardAvoidingView
        pointerEvents="box-none"
        behavior="padding"
        keyboardVerticalOffset={12}
        className="flex-1"
      >
        {children}
      </KeyboardAvoidingView>
    ),
    []
  );

  return (
    <KeyboardProvider>
      <HeroUINativeProvider
        config={{
          toast: {
            contentWrapper,
          },
        }}
      >
        {children}
      </HeroUINativeProvider>
    </KeyboardProvider>
  );
}

Default Props

Set global defaults for variant, placement, animation, and swipe behavior:

<HeroUINativeProvider
  config={{
    toast: {
      defaultProps: {
        variant: 'accent',
        placement: 'bottom',
        isSwipeable: false,
      },
    },
  }}
>
  {children}
</HeroUINativeProvider>

API Reference

Toast

ToastRootAnimation

Animation configuration for Toast component. Can be:

• false or "disabled": Disable only root animations
• "disable-all": Disable all animations including children
• true or undefined: Use default animations
• object: Custom animation configuration

Toast.Title

Toast.Description

Toast.Action

Toast.Action extends all props from Button component. Button variant is automatically determined based on toast variant but can be overridden.

For inherited props including onPress, isDisabled, and all Button props, see Button API Reference.

Toast.Close

Toast.Close extends all props from Button component.

For inherited props including isDisabled and all Button props, see Button API Reference.

ToastProviderProps

Props for configuring toast behavior globally via HeroUINativeProvider config prop.

ToastGlobalConfig

Global toast configuration used as defaults for all toasts unless overridden locally.

ToastInsets

Insets for spacing from screen edges. Values are added to safe area insets.

Hooks

useToast

Hook to access toast functionality. Must be used within a ToastProvider (provided by HeroUINativeProvider).

ToastManager

ToastShowOptions

Options for showing a toast. Can be either a config object with default styling or a custom component.

When using config object (without component):

When using custom component:

Special Notes

Styling Notes

Border as Padding

Toast uses border-[16px] class which serves as padding. This is intentional because when visible toasts have different heights, the toast adapts to the last visible toast height. In cases where a toast originally has one height and gets smaller when a new toast comes to stack, content might be visible behind the last toast without proper padding. The border ensures consistent spacing regardless of toast height changes.

For padding, use border classes. For actual borders, use outline classes.