# Toast
A temporary notification that appears at the bottom of the screen.
## Import
```tsx
import { Toast } from '@coinbase/cds-web/overlays/Toast'
```
## Examples
Use the `useToast` hook to show toasts. Call `toast.show()` with a message to display a temporary notification.
```jsx live
function BasicToastExample() {
const toast = useToast();
return ;
}
```
### Actions
Add an action button to the toast for quick user actions like "Undo" or "View".
```jsx live
function ToastWithActionExample() {
const toast = useToast();
const handleAction = useCallback(() => {
toast.show('Message sent', {
action: {
label: 'Undo',
onPress: () => console.log('Undo pressed'),
},
});
}, [toast]);
return ;
}
```
#### Without Close Button
Hide the close button when you want a cleaner appearance or when the toast should only be dismissed via the action or timeout.
```jsx live
function ToastWithoutCloseExample() {
const toast = useToast();
const handleAction = useCallback(() => {
toast.show('Item deleted', {
action: {
label: 'Undo',
onPress: () => console.log('Restored'),
},
hideCloseButton: true,
});
}, [toast]);
return ;
}
```
### Duration
Toast duration is automatically calculated based on content length:
- Base duration: 5 seconds
- With action: +2 seconds
- Long text (>50 characters): +0.3s per 10 additional characters
You can override the automatic calculation by providing a custom `duration` in milliseconds.
```jsx live
function CustomDurationExample() {
const toast = useToast();
return (
);
}
```
### Positioning
Use `bottomOffset` to adjust the vertical position of the toast. This is useful when you have bottom navigation or other fixed elements.
```jsx live
function BottomOffsetExample() {
const toast = useToast();
return (
);
}
```
### Styling
#### Variants
Use the `variant` prop to change the color surge effect on the toast background. This helps communicate the nature of the notification.
```jsx live
function VariantExample() {
const toast = useToast();
return (
);
}
```
### Lifecycle Callbacks
Use `onWillHide` and `onDidHide` to respond to toast dismissal. This is useful for cleanup or triggering subsequent actions.
```jsx live
function LifecycleCallbacksExample() {
const toast = useToast();
const [status, setStatus] = useState('Ready');
const handleShow = useCallback(() => {
setStatus('Toast visible');
toast.show('Saving changes...', {
onWillHide: () => setStatus('Toast hiding...'),
onDidHide: () => setStatus('Toast hidden'),
});
}, [toast]);
return (
Status: {status}
);
}
```
### Programmatic Control
#### Hiding Toasts
Use `toast.hide()` to programmatically dismiss the current toast.
```jsx live
function HideToastExample() {
const toast = useToast();
const showLongToast = useCallback(() => {
toast.show('This toast will stay until dismissed', { duration: 30000 });
}, [toast]);
return (
);
}
```
#### Clearing the Queue
When multiple toasts are triggered, they queue up. Use `toast.clearQueue()` to remove all pending toasts.
```jsx live
function ClearQueueExample() {
const toast = useToast();
const showMultiple = useCallback(() => {
toast.show('First toast');
toast.show('Second toast');
toast.show('Third toast');
}, [toast]);
return (
);
}
```
### Accessibility
Toast uses `role="alert"` for screen reader announcements. On web, the toast persists when the user hovers over it, giving them time to read the content.
For internationalization, you can customize the close button's accessibility label:
```jsx live
function AccessibilityExample() {
const toast = useToast();
const handleShow = useCallback(() => {
toast.show('Configuración guardada', {
closeButtonAccessibilityProps: {
accessibilityLabel: 'cerrar',
},
});
}, [toast]);
return ;
}
```
### Composed Examples
#### Form Submission Feedback
A common pattern is showing toast feedback after form actions.
```jsx live
function FormSubmissionExample() {
const toast = useToast();
const [isSubmitting, setIsSubmitting] = useState(false);
const handleSubmit = useCallback(async () => {
setIsSubmitting(true);
// Simulate API call
await new Promise((resolve) => setTimeout(resolve, 1000));
setIsSubmitting(false);
toast.show('Profile updated successfully', {
variant: 'bgPositive',
action: {
label: 'View',
onPress: () => console.log('Navigate to profile'),
},
});
}, [toast]);
return (
);
}
```
#### Clipboard Copy
Provide feedback when copying content to the clipboard.
```jsx live
function ClipboardCopyExample() {
const toast = useToast();
const walletAddress = '0x1234...5678';
const handleCopy = useCallback(async () => {
try {
await navigator.clipboard.writeText('0x1234567890abcdef1234567890abcdef12345678');
toast.show('Address copied to clipboard');
} catch (err) {
toast.show('Failed to copy', { variant: 'bgNegative' });
}
}, [toast]);
return (
{walletAddress}
);
}
```
#### Undo Delete Action
Implement an undo pattern for destructive actions.
```jsx live
function UndoDeleteExample() {
const toast = useToast();
const [items, setItems] = useState(['Item 1', 'Item 2', 'Item 3']);
const deletedItemRef = useRef(null);
const handleDelete = useCallback(
(index) => {
const deletedItem = items[index];
deletedItemRef.current = { item: deletedItem, index };
setItems((prev) => prev.filter((_, i) => i !== index));
toast.show(`"${deletedItem}" deleted`, {
variant: 'bgNegative',
action: {
label: 'Undo',
onPress: () => {
if (deletedItemRef.current) {
setItems((prev) => {
const newItems = [...prev];
newItems.splice(deletedItemRef.current.index, 0, deletedItemRef.current.item);
return newItems;
});
deletedItemRef.current = null;
}
},
},
});
},
[items, toast],
);
return (
{items.map((item, index) => (
{item}
handleDelete(index)}
accessibilityLabel={`Delete ${item}`}
/>
))}
{items.length === 0 && (
No items
)}
);
}
```
## Props
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | Yes | `-` | The message to be displayed in the toast |
| `action` | `ToastAction` | No | `-` | Optional toast action i.e. a CTA button |
| `alignContent` | `ResponsiveProp
` | No | `-` | - |
| `alignItems` | `ResponsiveProp` | No | `-` | - |
| `alignSelf` | `ResponsiveProp` | No | `-` | - |
| `as` | `div` | No | `-` | The underlying element or component the polymorphic component will render. Changing as also changes the inherited native props (e.g. href for as=a) and the expected ref type. |
| `aspectRatio` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `background` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `-` | - |
| `borderBottomLeftRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
| `borderBottomRightRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
| `borderBottomWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
| `borderColor` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `-` | - |
| `borderEndWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
| `borderRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
| `borderStartWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
| `borderTopLeftRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
| `borderTopRightRadius` | `0 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| 1000` | No | `-` | - |
| `borderTopWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
| `borderWidth` | `0 \| 100 \| 200 \| 300 \| 400 \| 500` | No | `-` | - |
| `bordered` | `boolean` | No | `-` | Add a border around all sides of the box. |
| `borderedBottom` | `boolean` | No | `-` | Add a border to the bottom side of the box. |
| `borderedEnd` | `boolean` | No | `-` | Add a border to the trailing side of the box. |
| `borderedHorizontal` | `boolean` | No | `-` | Add a border to the leading and trailing sides of the box. |
| `borderedStart` | `boolean` | No | `-` | Add a border to the leading side of the box. |
| `borderedTop` | `boolean` | No | `-` | Add a border to the top side of the box. |
| `borderedVertical` | `boolean` | No | `-` | Add a border to the top and bottom sides of the box. |
| `bottom` | `ResponsiveProp>` | No | `-` | - |
| `bottomOffset` | `string \| number` | No | `-` | The vertical offset from the bottom of the screen |
| `closeButtonAccessibilityProps` | `SharedAccessibilityProps` | No | `{ accessibilityLabel: "close" }` | Accessibility props are provided to ensure i18n support for all relevant a11y props |
| `color` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `-` | - |
| `columnGap` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `dangerouslySetBackground` | `string` | No | `-` | - |
| `disablePortal` | `boolean` | No | `-` | Disable React portal integration |
| `display` | `ResponsiveProp` | No | `-` | - |
| `elevation` | `0 \| 1 \| 2` | No | `-` | - |
| `flexBasis` | `ResponsiveProp>` | No | `-` | - |
| `flexDirection` | `ResponsiveProp` | No | `-` | - |
| `flexGrow` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset` | No | `-` | - |
| `flexShrink` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset` | No | `-` | - |
| `flexWrap` | `ResponsiveProp` | No | `-` | - |
| `font` | `ResponsiveProp` | No | `-` | - |
| `fontFamily` | `ResponsiveProp` | No | `-` | - |
| `fontSize` | `ResponsiveProp` | No | `-` | - |
| `fontWeight` | `ResponsiveProp` | No | `-` | - |
| `gap` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `grid` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| none` | No | `-` | - |
| `gridArea` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `gridAutoColumns` | `ResponsiveProp>` | No | `-` | - |
| `gridAutoFlow` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| row \| column \| dense` | No | `-` | - |
| `gridAutoRows` | `ResponsiveProp>` | No | `-` | - |
| `gridColumn` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `gridColumnEnd` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `gridColumnStart` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `gridRow` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `gridRowEnd` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `gridRowStart` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |
| `gridTemplate` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| none` | No | `-` | - |
| `gridTemplateAreas` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| none` | No | `-` | - |
| `gridTemplateColumns` | `ResponsiveProp>` | No | `-` | - |
| `gridTemplateRows` | `ResponsiveProp>` | No | `-` | - |
| `height` | `ResponsiveProp>` | No | `-` | - |
| `hideCloseButton` | `boolean` | No | `false` | Hide the close button on the right |
| `justifyContent` | `ResponsiveProp` | No | `-` | - |
| `key` | `Key \| null` | No | `-` | - |
| `left` | `ResponsiveProp>` | No | `-` | - |
| `lineHeight` | `ResponsiveProp` | No | `-` | - |
| `margin` | `ResponsiveProp<0 \| -3 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -4 \| -5 \| -6 \| -7 \| -8 \| -9 \| -10>` | No | `-` | - |
| `marginBottom` | `ResponsiveProp<0 \| -3 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -4 \| -5 \| -6 \| -7 \| -8 \| -9 \| -10>` | No | `-` | - |
| `marginEnd` | `ResponsiveProp<0 \| -3 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -4 \| -5 \| -6 \| -7 \| -8 \| -9 \| -10>` | No | `-` | - |
| `marginStart` | `ResponsiveProp<0 \| -3 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -4 \| -5 \| -6 \| -7 \| -8 \| -9 \| -10>` | No | `-` | - |
| `marginTop` | `ResponsiveProp<0 \| -3 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -4 \| -5 \| -6 \| -7 \| -8 \| -9 \| -10>` | No | `-` | - |
| `marginX` | `ResponsiveProp<0 \| -3 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -4 \| -5 \| -6 \| -7 \| -8 \| -9 \| -10>` | No | `-` | - |
| `marginY` | `ResponsiveProp<0 \| -3 \| -0.25 \| -0.5 \| -0.75 \| -1 \| -1.5 \| -2 \| -4 \| -5 \| -6 \| -7 \| -8 \| -9 \| -10>` | No | `-` | - |
| `maxHeight` | `ResponsiveProp>` | No | `-` | - |
| `maxWidth` | `ResponsiveProp>` | No | `-` | - |
| `minHeight` | `ResponsiveProp>` | No | `-` | - |
| `minWidth` | `ResponsiveProp>` | No | `-` | - |
| `onChange` | `FormEventHandler` | No | `-` | - |
| `onDidHide` | `(() => void)` | No | `-` | Callback fired after the component is hidden. |
| `onWillHide` | `(() => void)` | No | `-` | Callback fired before the component hides. |
| `opacity` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset` | No | `-` | - |
| `overflow` | `ResponsiveProp` | No | `-` | - |
| `padding` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `paddingBottom` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `paddingEnd` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `paddingStart` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `paddingTop` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `paddingX` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `paddingY` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `pin` | `top \| bottom \| left \| right \| all` | No | `-` | Direction in which to absolutely pin the box. |
| `position` | `ResponsiveProp` | No | `-` | - |
| `ref` | `((instance: ToastRefHandle \| null) => void) \| RefObject \| null` | No | `-` | - |
| `right` | `ResponsiveProp>` | No | `-` | - |
| `rowGap` | `0 \| 5 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 6 \| 7 \| 8 \| 9` | No | `-` | - |
| `style` | `CSSProperties` | No | `-` | - |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
| `textAlign` | `ResponsiveProp` | No | `-` | - |
| `textDecoration` | `ResponsiveProp` | No | `-` | - |
| `textTransform` | `ResponsiveProp` | No | `-` | - |
| `top` | `ResponsiveProp>` | No | `-` | - |
| `transform` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| none` | No | `-` | - |
| `userSelect` | `ResponsiveProp` | No | `-` | - |
| `variant` | `currentColor \| fg \| fgMuted \| fgInverse \| fgPrimary \| fgWarning \| fgPositive \| fgNegative \| bg \| bgAlternate \| bgInverse \| bgOverlay \| bgElevation1 \| bgElevation2 \| bgPrimary \| bgPrimaryWash \| bgSecondary \| bgTertiary \| bgSecondaryWash \| bgNegative \| bgNegativeWash \| bgPositive \| bgPositiveWash \| bgWarning \| bgWarningWash \| bgLine \| bgLineHeavy \| bgLineInverse \| bgLinePrimary \| bgLinePrimarySubtle \| accentSubtleRed \| accentBoldRed \| accentSubtleGreen \| accentBoldGreen \| accentSubtleBlue \| accentBoldBlue \| accentSubtlePurple \| accentBoldPurple \| accentSubtleYellow \| accentBoldYellow \| accentSubtleGray \| accentBoldGray \| transparent` | No | `primary` | Controls color surge of the Toast background |
| `visibility` | `ResponsiveProp` | No | `-` | - |
| `width` | `ResponsiveProp>` | No | `-` | - |
| `zIndex` | `-moz-initial \| inherit \| initial \| revert \| revert-layer \| unset \| auto` | No | `-` | - |