Toast - Vant 4

Toast

Intro

Black semi-transparent pop-up hint in the middle of the page, used for message notification, loading hint, operation result hint and other scenarios.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from'vue'; import { Toast } from'vant'; const app = createApp(); app.use(Toast);

Function Call

Vant provides some utility functions that can quickly evoke global Toast components.

For example, calling the showToast function will render a Toast directly in the page.

import { showToast } from'vant'; showToast('Some messages');

Usage

Text

Use the showToast method to display a text toast in the center of the screen.

import { showToast } from'vant'; showToast('Some messages');

Loading

Use the showLoadingToast method to display a loading toast. The forbidClick option can be used to disable background clicks.

import { showLoadingToast } from'vant'; showLoadingToast({ message: 'Loading...', forbidClick: true, });

Success/Fail

Use the showSuccessToast method to display a success message, and use the showFailToast method to display a failure message.

import { showSuccessToast, showFailToast } from'vant'; showSuccessToast('Success'); showFailToast('Fail');

Custom Icon

The icon option allows you to customize the icon by specifying either the icon name or an image URL, which is equivalent to the name attribute of the Icon component.

import { showToast, showLoadingToast } from'vant'; showToast({ message: 'Custom Icon', icon: 'like-o', }); showToast({ message: 'Custom Image', icon: 'https://fastly.jsdelivr.net/npm/@vant/assets/logo.png', });

The loadingType option allows you to customize the type of loading icon.

showLoadingToast({ message: 'Loading...', forbidClick: true, loadingType: 'spinner', });

Custom Position

By default, the Toast is rendered in the center of the screen. You can control the position of the Toast by using the position option.

import { showToast } from'vant'; showToast({ message: 'Top', position: 'top', }); showToast({ message: 'Bottom', position: 'bottom', });

Word Break

The wordBreak option controls how the text in the Toast is truncated when it exceeds the available space. The default value is break-all, and the optional values are break-word and normal.

import { showToast } from'vant'; showToast({ message: 'This message will contain a incomprehensibilities long word.', wordBreak: 'break-all', }); showToast({ message: 'This message will contain a incomprehensibilities long word.', wordBreak: 'break-word', });

Update Message

When executing the Toast method, it returns the corresponding Toast instance. You can dynamically update the message by modifying the message property on the instance.

import { showLoadingToast, closeToast } from'vant'; const toast = showLoadingToast({ duration: 0, forbidClick: true, loadingType: 'spinner', message: '3 seconds', }); let second = 3; const timer = setInterval(() => { second--; if (second) { toast.message = `${second} seconds`; } else { clearInterval(timer); closeToast(); } }, 1000);

Singleton

The Toast is implemented as a singleton by default, which means that only one Toast can exist at a time. If you need to display multiple Toasts at the same time, you can refer to the following example:

import { showToast, showSuccessToast, allowMultipleToast } from'vant'; allowMultipleToast(); const toast1 = showToast('First Toast'); const toast2 = showSuccessToast('Second Toast'); toast1.close(); toast2.close();

Set Default Options

You can globally modify the default configuration of the showToast and other methods by using the setToastDefaultOptions function.

import { setToastDefaultOptions, resetToastDefaultOptions } from'vant'; setToastDefaultOptions({ duration: 2000 }); setToastDefaultOptions('loading', { forbidClick: true }); resetToastDefaultOptions(); resetToastDefaultOptions('loading');

Use Toast Component

If you need to embed components or other custom content within the Toast, you can directly use the Toast component and customize it using the message slot. Before using it, you need to register the component using app.use or other methods.

import { ref } from'vue'; exportdefault { setup() { const show = ref(false); return { show }; }, };

API

Methods

Vant exports following Toast utility functions:

Name	Description	Attribute	Return value
showToast	Display a text toast	`ToastOptions	string`
showLoadingToast	Display a loading toast	`ToastOptions	string`
showSuccessToast	Display a success toast	`ToastOptions	string`
showFailToast	Display a fail toast	`ToastOptions	string`
closeToast	Close the currently displayed toast	closeAll: boolean	void
allowMultipleToast	Allow multiple toasts to be displayed as the same time	-	void
setToastDefaultOptions	Modify the default configuration that affects all showToast calls. Specify the type parameter to modify the default configuration of a specific type of toast	`type	ToastOptions`
resetToastDefaultOptions	Reset the default configuration that affects all showToast calls. Specify the type parameter to reset the default configuration of a specific type of toast	type	void

ToastOptions

When calling the showToast and other related methods, the following options are supported:

Attribute	Description	Type	Default
type	Can be set to loading``success``fail``html	ToastType	text
position	Can be set to top``middle``bottom	ToastPosition	middle
message	Message	string	''
wordBreak	Can be set to normal``break-all``break-word	ToastWordBreak	'break-all'
icon	Custom icon	string	-
iconSize	Custom icon size	*number	string*
iconPrefix	Icon className prefix	string	van-icon
overlay	Whether to show overlay	boolean	false
forbidClick	Whether to forbid click background	boolean	false
closeOnClick	Whether to close after clicked	boolean	false
closeOnClickOverlay	Whether to close when overlay is clicked	boolean	false
loadingType	Loading icon type, can be set to spinner	string	circular
duration	Toast duration(ms), won't disappear if value is 0	number	2000
className	Custom className	*string	Array
overlayClass	Custom overlay class	*string	Array
overlayStyle	Custom overlay style	object	-
transition	Transition, equivalent to name prop of transition	string	van-fade

| teleport | Specifies a target element where Toast will be mounted | string | Element | body | | zIndex | Set the z-index to a fixed value | number | string | 2000+ | | onClose | Callback function after close | Function | - | | onOpened | Callback function after opened | Function | - |

Props

When using Toast as a component, the following props are supported:

Attribute	Description	Type	Default
v-model:show	Whether to show toast	boolean	false
type	Can be set to loading``success``fail``html	ToastType	text
position	Can be set to top``middle``bottom	ToastPosition	middle
message	Message	string	''
word-break	Can be set to normal``break-all``break-word	ToastWordBreak	'break-all'
icon	Custom icon	string	-
icon-size	Custom icon size	*number	string*
icon-prefix	Icon className prefix	string	van-icon
overlay	Whether to show overlay	boolean	false
forbid-click	Whether to forbid click background	boolean	false
close-on-click	Whether to close after clicked	boolean	false
close-on-click-overlay	Whether to close when overlay is clicked	boolean	false
loading-type	Loading icon type, can be set to spinner	string	circular
duration	Toast duration(ms), won't disappear if value is 0	number	2000
class-name	Custom className	*string	Array
overlay-class	Custom overlay class	*string	Array
overlay-style	Custom overlay style	object	-
transition	Transition, equivalent to name prop of transition	string	van-fade

| teleport | Specifies a target element where Toast will be mounted | string | Element | body | | z-index | Set the z-index to a fixed value | number | string | 2000+ |

Events

When using Toast as a component, the following events are supported:

Event	Description	Parameters
close	Callback function after close	-
opened	Callback function after opened	-

Slots

You can use following slots when using Toast component:

Name	Description
message	Custom message

Types

The component exports the following type definitions:

importtype { ToastType, ToastProps, ToastOptions, ToastPosition, ToastWordBreak, ToastWrapperInstance, } from'vant';

Theming

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-toast-max-width	70%	-
--van-toast-font-size	var(--van-font-size-md)	-
--van-toast-text-color	var(--van-white)	-
--van-toast-loading-icon-color	var(--van-white)	-
--van-toast-line-height	var(--van-line-height-md)	-
--van-toast-radius	var(--van-radius-lg)	-
--van-toast-background	fade(var(--van-black), 70%)	-
--van-toast-icon-size	36px	-
--van-toast-text-min-width	96px	-
--van-toast-text-padding	var(--van-padding-xs) var(--van-padding-sm)	-
--van-toast-default-padding	var(--van-padding-md)	-
--van-toast-default-width	88px	-
--van-toast-default-min-height	88px	-
--van-toast-position-top-distance	20%	-
--van-toast-position-bottom-distance	20%	-

FAQ

Compilation error when referencing showToast?

If you encounter the following error when referencing the showToast method, it indicates that the project is using the babel-plugin-import plugin, which causes incorrect compilation.

These dependencies were not found: * vant/es/show-toast in ./src/xxx.js * vant/es/show-toast/style in ./src/xxx.js

Starting from version 4.0, Vant no longer supports the babel-plugin-import plugin. Please refer to the migration guide to remove this plugin.

Style Issues When Using showToast with On-Demand Component Import?

When integrating Vant using the on-demand component import method, using functions like showToast does not require explicit import. Doing so can cause style issues.

// The following import is not neededimport { showToast } from'vant'

This is because when you explicitly import functions like showToast, @vant/auto-import-resolver will not automatically import the style resources for Toast, leading to missing styles and resulting in style issues.

There are two solutions:

• Do not explicitly import showToast when using it.
• If you must explicitly import showToast, you also need to manually import the related styles for the Toast component.

import { showToast } from'vant'import'vant/lib/toast/style'