Toast

The Toast component provides non-blocking notification messages that appear temporarily to give feedback about an operation or event. Title and body each accept full <Text> props via titleProps / bodyProps — also forwarded by every useToast() shortcut.

Source

View source code

LLM docs

LLM documentation

Package

@platform-blocks/react-ui-library

Examples

⁽⁹⁾

Properties

⁽⁴⁶⁾

Playground

Basic Usage

Call toast.success with a title, message, and optional autoHide value to show a standard confirmation toast.

Loading demo…

import
 
{
 
Button
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
 
  
const
 handlePress 
=
 
(
)
 
=>
 
{
    toast
.
success
(
{
      title
:
 
'Success!'
,
      message
:
 
'The operation finished without issues.'
,
      autoHide
:
 
4000
,
    
}
)
;
  
}
;
 
  
return
 
<Button
 
onPress
=
{
handlePress
}
>
Show
 success toast
</Button
>
;
}

Positions

Set the position option to anchor the toast stack to any corner or edge of the viewport.

Loading demo…

import
 
{
 
Block
,
 
Button
,
 
Row
,
 
Text
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
const
 toastPositions 
=
 
[
  
'top-left'
,
  
'top-center'
,
 
  
'top-right'
,
  
'bottom-left'
,
  
'bottom-center'
,
  
'bottom-right'
,
]
 as 
const
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
 
  
const
 showToastAtPosition 
=
 
(
position
:
 typeof toastPositions
[
number
]
)
 
=>
 
{
    toast
.
show
(
{
      title
:
 
`Toast at ${position}`
,
      message
:
 
`This toast appears at ${position} position.`
,
      position
,
    
}
)
;
  
}
;
 
  
return
 
(
    
<Block
>
      
<Text
 
size
=
"xs"
 
color
=
"secondary"
>
        
Pass
 
`position`
 to align the toast container with your layout
.
      
</Text
>
      
<Row
 
gap
=
"xs"
 
wrap
=
"wrap"
>
        
{
toastPositions
.
map
(
(
position
)
 
=>
 
(
          
<Button
 
key
=
{
position
}
 
size
=
"sm"
 
onPress
=
{
(
)
 
=>
 
showToastAtPosition
(
position
)
}
>
            
{
position
}
          
</Button
>
        
)
)
}
      
</Row
>
    
</Block
>
  
)
;
}

Visual Variants

Use the variant prop to control the toast surface: filled (solid color with auto-contrast text), outline (surface with a full colored border), or light (subtle surface with a colored left accent). Combine it with any color or severity helper.

Loading demo…

import
 
{
 
Block
,
 
Button
,
 
Icon
,
 
Row
,
 
Text
,
 
Toast
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
const
 
VARIANTS
 
=
 
[
'light'
,
 
'filled'
,
 
'outline'
]
 as 
const
;
 
type
 
ToastVariant
 
=
 
(
typeof 
VARIANTS
)
[
number
]
;
 
const
 
COPY
:
 
Record
<ToastVariant
,
 
string
>
 
=
 
{
  light
:
 
'Subtle surface with a colored left accent.'
,
  filled
:
 
'Solid fill with auto-contrast text.'
,
  outline
:
 
'Surface with a full colored border.'
,
}
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
 
  
return
 
(
    
<Block
 
gap
=
"md"
>
      
<Text
 
size
=
"xs"
 
color
=
"secondary"
>
        
The
 
`variant`
 prop controls the toast surface
.
 
Each
 preview below pairs
        the variant with the 
`success`
 severity — swap 
`severity`
 or 
`color`
 to
        recolor 
any
 of them
.
      
</Text
>
 
      
{
VARIANTS
.
map
(
(
variant
)
 
=>
 
(
        
<Block
 
key
=
{
variant
}
 
gap
=
"xs"
>
          
<Text
 
variant
=
"small"
 
color
=
"secondary"
>
            
{
variant
}
          
</Text
>
          
<Toast
            visible
            persistent
            
autoHide
=
{
0
}
            
variant
=
{
variant
}
            
severity
=
"success"
            
title
=
"Changes saved"
            
icon
=
{
<Icon
 
name
=
"success"
 
variant
=
"filled"
 
/>
}
            
withCloseButton
=
{
false
}
          
>
            
{
COPY
[
variant
]
}
          
</Toast
>
        
</Block
>
      
)
)
}
 
      
<Row
 
gap
=
"xs"
 
wrap
=
"wrap"
>
        
{
VARIANTS
.
map
(
(
variant
)
 
=>
 
(
          
<Button
            
key
=
{
variant
}
            
variant
=
{
variant 
===
 
'filled'
 
?
 
'filled'
 
:
 
'outline'
}
            
onPress
=
{
(
)
 
=>
              toast
.
success
(
{
                variant
,
                title
:
 
`${variant} toast`
,
                message
:
 
COPY
[
variant
]
,
              
}
)
            
}
          
>
            
Show
 
{
variant
}
          
</Button
>
        
)
)
}
      
</Row
>
    
</Block
>
  
)
;
}

Size Tokens

The size prop supports the full seven-token scale (xs, sm, md, lg, xl, 2xl, 3xl) and scales padding, title and body typography, the leading icon, action buttons, and the close button together. A number is read as the title font size and scales the rest proportionally. Set defaultSize on ToastProvider to change the default for every toast.

Loading demo…

import
 
{
 
Block
,
 
Button
,
 
Icon
,
 
Row
,
 
Text
,
 
Toast
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
const
 
SIZES
 
=
 
[
'xs'
,
 
'sm'
,
 
'md'
,
 
'lg'
,
 
'xl'
,
 
'2xl'
,
 
'3xl'
]
 as 
const
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
 
  
return
 
(
    
<Block
 
gap
=
"md"
>
      
<Text
 
size
=
"xs"
 
color
=
"secondary"
>
        
`size`
 accepts all seven component tokens
.
 
Padding
,
 title and body 
type
,
        the leading icon
,
 and the close button all scale together — pass a
        
number
 instead of a token to scale 
from
 a custom title size
.
 
The
        previews are 
static
;
 the buttons below fire real toasts at each size
.
      
</Text
>
 
      
{
SIZES
.
map
(
(
size
)
 
=>
 
(
        
<Block
 
key
=
{
size
}
 
gap
=
"xs"
>
          
<Text
 
variant
=
"small"
 
color
=
"secondary"
>
            
{
size
}
          
</Text
>
          
<Toast
            visible
            persistent
            
autoHide
=
{
0
}
            
size
=
{
size
}
            
variant
=
"light"
            
severity
=
"info"
            
title
=
"Sync complete"
            
icon
=
{
<Icon
 
name
=
"info"
 
variant
=
"filled"
 
/>
}
            
withCloseButton
=
{
false
}
          
>
            
Everything
 is up to date
.
          
</Toast
>
        
</Block
>
      
)
)
}
 
      
<Row
 
gap
=
"xs"
 
wrap
=
"wrap"
>
        
{
SIZES
.
map
(
(
size
)
 
=>
 
(
          
<Button
            
key
=
{
size
}
            
size
=
"sm"
            
variant
=
"outline"
            
onPress
=
{
(
)
 
=>
              toast
.
info
(
{
                size
,
                title
:
 
`Size ${size}`
,
                message
:
 
'Toasts keep their proportions at every token.'
,
              
}
)
            
}
          
>
            
{
size
}
          
</Button
>
        
)
)
}
      
</Row
>
    
</Block
>
  
)
;
}

Severity Helpers

Use toast.success, toast.warning, toast.error, and toast.info to render consistent styling and icons for each severity.

Loading demo…

import
 
{
 
Block
,
 
Button
,
 
Row
,
 
Text
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
 
  
const
 showSuccessToast 
=
 
(
)
 
=>
 
{
    toast
.
success
(
{
      title
:
 
'Success'
,
      message
:
 
'The request completed correctly.'
,
    
}
)
;
  
}
;
 
  
const
 showWarningToast 
=
 
(
)
 
=>
 
{
    toast
.
warning
(
{
      title
:
 
'Warning'
,
      message
:
 
'Double-check the highlighted fields.'
,
    
}
)
;
  
}
;
 
  
const
 showErrorToast 
=
 
(
)
 
=>
 
{
    toast
.
error
(
{
      title
:
 
'Error'
,
      message
:
 
'Something went wrong.'
,
    
}
)
;
  
}
;
 
  
const
 showInfoToast 
=
 
(
)
 
=>
 
{
    toast
.
info
(
{
      title
:
 
'Info'
,
      message
:
 
'Here is some additional context.'
,
    
}
)
;
  
}
;
 
  
return
 
(
    
<Block
>
      
<Text
 
size
=
"xs"
 
color
=
"secondary"
>
        
Use
 the severity helpers to render consistent styling 
for
 each toast 
type
.
      
</Text
>
      
<Row
 
gap
=
"xs"
 
wrap
=
"wrap"
>
        
<Button
 
onPress
=
{
showSuccessToast
}
 
variant
=
"filled"
 
color
=
"success"
>
          
Success
        
</Button
>
        
<Button
 
onPress
=
{
showWarningToast
}
 
variant
=
"filled"
 
color
=
"warning"
>
          
Warning
        
</Button
>
        
<Button
 
onPress
=
{
showErrorToast
}
 
variant
=
"filled"
 
color
=
"error"
>
          
Error
        
</Button
>
        
<Button
 
onPress
=
{
showInfoToast
}
 
variant
=
"outline"
>
          
Info
        
</Button
>
      
</Row
>
    
</Block
>
  
)
;
}

Interactive Features

Add actions, toggle persistent, or shorten autoHide to tailor toast interactions for acknowledgements, warnings, and ephemeral notices.

Loading demo…

import
 
{
 
Block
,
 
Button
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
 
  
const
 showActionToast 
=
 
(
)
 
=>
 
{
    toast
.
show
(
{
      title
:
 
'File uploaded'
,
      message
:
 
'Your file has been uploaded successfully.'
,
      actions
:
 
[
        
{
          label
:
 
'Undo'
,
          onPress
:
 
(
)
 
=>
 toast
.
info
(
'Upload reverted'
)
,
        
}
,
      
]
,
    
}
)
;
  
}
;
 
  
const
 showPersistentToast 
=
 
(
)
 
=>
 
{
    
let
 toastId 
=
 
''
;
    toastId 
=
 toast
.
show
(
{
      title
:
 
'Important notice'
,
      message
:
 
'This toast stays visible until dismissed.'
,
      persistent
:
 
true
,
      actions
:
 
[
        
{
          label
:
 
'Dismiss'
,
          onPress
:
 
(
)
 
=>
 toast
.
hide
(
toastId
)
,
        
}
,
      
]
,
    
}
)
;
  
}
;
 
  
const
 showTimedToast 
=
 
(
)
 
=>
 
{
    toast
.
show
(
{
      title
:
 
'Quick message'
,
      message
:
 
'This one hides after two seconds.'
,
      autoHide
:
 
2000
,
    
}
)
;
  
}
;
 
  
return
 
(
    
<Block
>
      
<Button
 
onPress
=
{
showActionToast
}
>
Toast
 with action
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
showPersistentToast
}
>
        
Persistent
 toast
      
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
showTimedToast
}
>
        
Quick
 
toast
 
(
2s
)
      
</Button
>
    
</Block
>
  
)
;
}

Stacking

Toasts at the same position form a stack. The newest one always takes the slot against the anchored edge and the rest move out of its way; when one is dismissed, the toasts behind it slide into the gap while it fades. Hovering — or tabbing into — any toast pauses the countdown on the whole stack, and resumes it with the time that was left. limit caps how many are on screen at once, retiring the oldest with its normal exit rather than deleting it.

Loading demo…

import
 
{
 useRef 
}
 
from
 
'react'
;
 
import
 
{
 
Block
,
 
Button
,
 
Text
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
  
const
 counter 
=
 
useRef
(
0
)
;
 
  
const
 push 
=
 
(
)
 
=>
 
{
    counter
.
current 
+=
 
1
;
    
const
 n 
=
 counter
.
current
;
    toast
.
show
(
{
      title
:
 
`Message ${n}`
,
      message
:
 
'Dismiss one from the middle to watch the stack close the gap.'
,
      severity
:
 
(
[
'info'
,
 
'success'
,
 
'warning'
,
 
'error'
]
 as 
const
)
[
n 
%
 
4
]
,
      autoHide
:
 
6000
,
    
}
)
;
  
}
;
 
  
const
 pushBurst 
=
 
(
)
 
=>
 
{
    toast
.
batch
(
      
Array
.
from
(
{
 length
:
 
5
 
}
,
 
(
_
,
 index
)
 
=>
 
(
{
        title
:
 
`Burst ${index + 1}`
,
        message
:
 
'Five at once — the limit retires the oldest.'
,
        severity
:
 
'info'
 as 
const
,
      
}
)
)
    
)
;
  
}
;
 
  
return
 
(
    
<Block
>
      
<Button
 
onPress
=
{
push
}
>
Add
 a toast
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
pushBurst
}
>
        
Add
 five at once
      
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
(
)
 
=>
 toast
.
hideAll
(
)
}
>
        
Dismiss
 all
      
</Button
>
      
<Text
 
size
=
"xs"
 
color
=
"secondary"
>
        
Hover
 the stack to hold every toast open
.
      
</Text
>
    
</Block
>
  
)
;
}

Enhanced Features

Combine swipe gestures, custom animationConfig, batch helpers, and toast.promise to coordinate rich toast experiences.

Loading demo…

import
 
{
 useState 
}
 
from
 
'react'
;
 
import
 
{
 
Block
,
 
Button
,
 
Text
,
 
Toast
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
  
const
 
[
loading
,
 setLoading
]
 
=
 
useState
(
false
)
;
 
  
const
 showSwipeableToast 
=
 
(
)
 
=>
 
{
    toast
.
info
(
{
      title
:
 
'Swipe me!'
,
      message
:
 
'Drag horizontally to dismiss this toast.'
,
      swipeConfig
:
 
{
        enabled
:
 
true
,
        threshold
:
 
150
,
        direction
:
 
'horizontal'
,
      
}
,
      onSwipeDismiss
:
 
(
)
 
=>
 
{
        console
.
log
(
'Toast dismissed via swipe'
)
;
      
}
,
      persistent
:
 
true
,
    
}
)
;
  
}
;
 
  
const
 showAnimatedToast 
=
 
(
)
 
=>
 
{
    toast
.
success
(
{
      title
:
 
'Spring motion'
,
      message
:
 
'Bounce animation with custom spring physics.'
,
      animationConfig
:
 
{
        
type
:
 
'bounce'
,
        springConfig
:
 
{
          damping
:
 
10
,
          stiffness
:
 
100
,
        
}
,
      
}
,
    
}
)
;
  
}
;
 
  
const
 showScaleToast 
=
 
(
)
 
=>
 
{
    toast
.
warning
(
{
      title
:
 
'Scale in'
,
      message
:
 
'Combines scale animation with bidirectional swipe.'
,
      animationConfig
:
 
{
        
type
:
 
'scale'
,
        duration
:
 
500
,
      
}
,
      swipeConfig
:
 
{
        enabled
:
 
true
,
        direction
:
 
'both'
,
      
}
,
    
}
)
;
  
}
;
 
  
const
 showToastWithActions 
=
 
(
)
 
=>
 
{
    toast
.
info
(
{
      title
:
 
'Actions'
,
      message
:
 
'Toasts can render multiple CTA buttons.'
,
      actions
:
 
[
        
{
          label
:
 
'Retry'
,
          onPress
:
 
(
)
 
=>
 toast
.
success
(
'Retrying…'
)
,
        
}
,
        
{
          label
:
 
'Cancel'
,
          onPress
:
 
(
)
 
=>
 toast
.
error
(
'Cancelled'
)
,
        
}
,
      
]
,
      persistent
:
 
true
,
    
}
)
;
  
}
;
 
  
const
 showBatchToasts 
=
 
(
)
 
=>
 
{
    toast
.
batch
(
[
      
{
        title
:
 
'Batch 1'
,
        message
:
 
'First toast in batch'
,
        severity
:
 
'info'
,
        groupId
:
 
'batch-demo'
,
      
}
,
      
{
        title
:
 
'Batch 2'
,
        message
:
 
'Second toast in batch'
,
        severity
:
 
'success'
,
        groupId
:
 
'batch-demo'
,
      
}
,
      
{
        title
:
 
'Batch 3'
,
        message
:
 
'Third toast in batch'
,
        severity
:
 
'warning'
,
        groupId
:
 
'batch-demo'
,
      
}
,
    
]
)
;
  
}
;
 
  
const
 hideBatchToasts 
=
 
(
)
 
=>
 
{
    toast
.
hideGroup
(
'batch-demo'
)
;
  
}
;
 
  
const
 showPromiseToast 
=
 
async
 
(
)
 
=>
 
{
    
setLoading
(
true
)
;
 
    
const
 mockApiCall 
=
 
(
)
 
=>
      
new
 
Promise
<
string
>
(
(
resolve
,
 reject
)
 
=>
 
{
        
setTimeout
(
(
)
 
=>
 
{
          
if
 
(
Math
.
random
(
)
 
>
 
0.5
)
 
{
            
resolve
(
'Success!'
)
;
          
}
 
else
 
{
            
reject
(
'Failed!'
)
;
          
}
        
}
,
 
2000
)
;
      
}
)
;
 
    
try
 
{
      
await
 toast
.
promise
(
mockApiCall
(
)
,
 
{
        pending
:
 
'Loading data…'
,
        success
:
 
(
data
)
 
=>
 
`Operation completed: ${data}`
,
        error
:
 
(
error
)
 
=>
 
`Operation failed: ${error.message}`
,
      
}
)
;
    
}
 
finally
 
{
      
setLoading
(
false
)
;
    
}
  
}
;
 
  
return
 
(
    
<Block
>
      
<Button
 
onPress
=
{
showSwipeableToast
}
>
Swipe
 to dismiss
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
showAnimatedToast
}
>
        
Bounce
 animation
      
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
showScaleToast
}
>
        
Scale
 animation 
+
 swipe
      
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
showToastWithActions
}
>
        
Toast
 with actions
      
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
showBatchToasts
}
>
        
Show
 batch toasts
      
</Button
>
      
<Button
 
variant
=
"outline"
 
onPress
=
{
hideBatchToasts
}
>
        
Hide
 batch toasts
      
</Button
>
      
<Button
 
variant
=
"outline"
 
loading
=
{
loading
}
 
onPress
=
{
showPromiseToast
}
>
        
Promise
 integration
      
</Button
>
 
      
<Block
>
        
<Text
 
size
=
"xs"
 
color
=
"secondary"
>
          
Tap
-
to
-
dismiss example
:
        
</Text
>
        
<Toast
          visible
          
title
=
"Tap me!"
          
severity
=
"info"
          dismissOnTap
          
onClose
=
{
(
)
 
=>
 console
.
log
(
'Tapped!'
)
}
          
position
=
"bottom"
        
>
          
This
 toast can be dismissed by tapping
.
        
</Toast
>
      
</Block
>
    
</Block
>
  
)
;
}

Text customization

titleProps and bodyProps accept any <Text> props (ff, weight, size, color, style…) and apply them to the toast title and body slots. Useful for matching toast typography to your brand.

Loading demo…

import
 
{
 
Block
,
 
Button
,
 useToast 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 toast 
=
 
useToast
(
)
;
 
  
return
 
(
    
<Block
>
      
<Button
        
onPress
=
{
(
)
 
=>
 
{
          toast
.
show
(
{
            title
:
 
'Default styling'
,
            message
:
 
'No custom title or body props.'
,
            severity
:
 
'info'
,
            autoHide
:
 
4000
,
          
}
)
;
        
}
}
      
>
        
Default
 toast
      
</Button
>
 
      
<Button
        
onPress
=
{
(
)
 
=>
 
{
          toast
.
show
(
{
            title
:
 
'Bold uppercase title'
,
            message
:
 
'Title rendered with monospace + tracking.'
,
            severity
:
 
'success'
,
            autoHide
:
 
4000
,
            titleProps
:
 
{
              ff
:
 
'monospace'
,
              weight
:
 
'700'
,
              uppercase
:
 
true
,
              tracking
:
 
1
,
              size
:
 
'sm'
,
            
}
,
            bodyProps
:
 
{
 size
:
 
'sm'
 
}
,
          
}
)
;
        
}
}
      
>
        
Tracked
 uppercase title
      
</Button
>
 
      
<Button
        
onPress
=
{
(
)
 
=>
 
{
          toast
.
show
(
{
            title
:
 
'Brand serif title'
,
            message
:
 
'Title in Georgia, body in default font.'
,
            severity
:
 
'warning'
,
            autoHide
:
 
4000
,
            titleProps
:
 
{
 ff
:
 
'Georgia, serif'
,
 size
:
 
'lg'
 
}
,
          
}
)
;
        
}
}
      
>
        
Custom
 font on title
      
</Button
>
    
</Block
>
  
)
;
}

Scan to open this page on your phonereact-ui-library.com/components/Toast

</>

react-ui-library

100+ accessible, themeable components that work seamlessly across iOS, Android, and Web.

A Platform Blocks product.

Quick Links

Components Charts Hooks

Docs

Getting Started Localization llms.txt

Resources

FAQ Changelog Accessibility Sitemap