Toast Options
Complete reference for all available toast configuration options.
The ToastOptions interface defines all available options when creating a toast.
interface ToastOptions {
type?: "success" | "error" | "info" | "warning";
title: string;
description?: string;
duration?: number;
position?: Position;
icon?: string;
showIcon?: boolean;
showProgress?: boolean;
actions?: Action[];
actionsLayout?: "horizontal" | "vertical";
avatar?: Avatar;
maxToasts?: number;
ui?: UIOverrides;
}
interface Action {
label: string;
onClick: () => void;
}
interface Avatar {
type?: "image" | "icon" | "text";
src?: string; // image
icon?: string; // icon
text?: string; // text
}
interface UIOverrides {
root?: string; // Toast container
title?: string; // Title element
description?: string; // Description element
icon?: string; // Icon wrapper
actions?: string; // Actions container
action?: string; // Individual action button
progress?: string; // Progress bar
avatar?: string; // Avatar container
}
Type: 'success' | 'error' | 'info' | 'warning'
Default: 'info'
The type of toast notification, which affects the default styling and icon.
<script setup>
const toast = useToast();
toast.add({ type: "success", title: "Success!" });
</script>
<script setup>
const toast = useToast();
toast.add({ type: "error", title: "Error!" });
</script>
<script setup>
const toast = useToast();
toast.add({ type: "info", title: "Info!" });
</script>
<script setup>
const toast = useToast();
toast.add({ type: "warning", title: "Warning!" });
</script>
Type: string
Required: Yes
The main heading text of the toast.
<script setup>
const toast = useToast();
toast.success("Operation Complete");
</script>
Type: string
Default: undefined
Additional descriptive text displayed below the title.
<script setup>
const toast = useToast();
toast.success("File Saved", "Your changes have been saved successfully");
</script>
Type: number
Default: 5000
How long the toast remains visible in milliseconds. Set to Infinity for persistent toasts.
<script setup>
const toast = useToast();
toast.info("Quick message", "", { duration: 2000 });
</script>
<script setup>
const toast = useToast();
toast.info("Important", "Read carefully", { duration: 10000 });
</script>
<script setup>
const toast = useToast();
toast.warning("Critical", "Requires action", { duration: Infinity });
</script>
Type: 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center'
Default: 'top-right'
Where the toast appears on screen.
<script setup>
const toast = useToast();
toast.info("Top Right", "", { position: "top-right" });
</script>
<script setup>
const toast = useToast();
toast.info("Bottom Center", "", { position: "bottom-center" });
</script>
Type: string
Default: Type-specific default icon
Custom icon name from Nuxt Icon library.
<script setup>
const toast = useToast();
toast.add({
type: "info",
title: "Custom Icon",
icon: "i-lucide-heart",
});
</script>
Type: boolean
Default: true
Whether to display the icon.
<script setup>
const toast = useToast();
toast.success("No Icon", "", { showIcon: false });
</script>
Type: boolean
Default: false
Display a progress bar showing remaining time.
<script setup>
const toast = useToast();
toast.info("Processing", "With progress bar", {
showProgress: true,
duration: 8000,
});
</script>
Type: Action[]
Default: undefined
Array of action buttons to display.
<script setup>
const toast = useToast();
toast.add({
type: "warning",
title: "Confirm Delete",
actions: [
{
label: "Delete",
onClick: () => {
console.log("Deleted");
},
},
{
label: "Cancel",
onClick: () => {
toast.clear();
},
},
],
});
</script>
Type: 'horizontal' | 'vertical'
Default: 'horizontal'
How to arrange action buttons.
<script setup>
const toast = useToast();
toast.add({
type: "info",
title: "Choose Layout",
actionsLayout: "vertical",
actions: [
{ label: "Option 1", onClick: () => {} },
{ label: "Option 2", onClick: () => {} },
],
});
</script>
<script setup>
const toast = useToast();
toast.add({
type: "info",
title: "Choose Layout",
actionsLayout: "horizontal",
actions: [
{ label: "Option 1", onClick: () => {} },
{ label: "Option 2", onClick: () => {} },
],
});
</script>
Type: Avatar
Default: undefined
Display an avatar in the toast.
<script setup>
const toast = useToast();
toast.add({
type: "info",
title: "John mentioned you",
avatar: {
type: "image",
src: "https://i.pravatar.cc/150?img=12",
},
});
</script>
<script setup>
const toast = useToast();
toast.add({
type: "success",
title: "Achievement",
avatar: {
type: "icon",
icon: "i-lucide-trophy",
},
});
</script>
<script setup>
const toast = useToast();
toast.add({
type: "info",
title: "Message from Sarah",
avatar: {
type: "text",
text: "SK",
},
});
</script>
Type: number
Default: Global config value (default: 5)
Override the maximum number of visible toasts for this specific toast.
<script setup>
const toast = useToast();
toast.add({
title: "Replace All",
maxToasts: 1, // Only show this toast, clear all others
});
</script>
Type: UIOverrides
Default: undefined
Override default styles with custom Tailwind CSS classes.
<script setup>
const toast = useToast();
toast.add({
type: "success",
title: "Custom Styling",
description: "With Tailwind classes",
ui: {
root: "rounded-2xl border-2 border-dashed border-primary-500",
title: "text-xl font-bold",
description: "text-sm italic",
},
});
</script>
Here's a toast using multiple options:
<script setup>
const toast = useToast();
toast.add({
type: "warning",
title: "Review Required",
description: "Your approval is needed for this design",
duration: 10000,
position: "top-right",
showProgress: true,
avatar: {
type: "image",
src: "https://i.pravatar.cc/150?img=5",
},
actions: [
{
label: "Approve",
onClick: () => {
toast.success("Approved", "Design has been approved");
},
},
{
label: "Reject",
onClick: () => {
toast.error("Rejected", "Design has been rejected");
},
},
],
ui: {
root: "shadow-xl ring-1 ring-black/5",
},
});
</script>
