svelte-french-toast

To use svelte-french-toast, you must first mount the <Toaster /> component at the top level of your Svelte application. Once the toaster is mounted, you can trigger notifications using the toast API (e.g., toast.success(), toast.error(), etc.) from anywhere in your application.

<script>
	import toast, {Toaster} from 'svelte-french-toast'

	function handleClick() {
		toast.success('Hello, world!')
	}
</script>

<Toaster />
<button type="button" on:click={handleClick}>Toast</button>

Install the package using your preferred package manager:

npm install svelte-french-toast

# or

pnpm install svelte-french-toast

# or

yarn add svelte-french-toast

When triggering a toast, you can pass options to customize its look and feel. These options are defined by ToastOptions and can be applied individually to a single toast call.

Available Options:

• id: A unique identifier for the toast.
• icon: A Renderable (Svelte component, string, or null) to display as an icon.
• duration: How long the toast stays visible (in milliseconds).
• ariaProps: Accessibility properties including role ('status' | 'alert') and 'aria-live' ('assertive' | 'off' | 'polite').
• className: A CSS class for the toast.
• style: Inline CSS styles for the toast.
• position: Overrides the global Toaster position.
• iconTheme: An IconTheme object specifying primary and secondary colors.
• props: Custom properties passed to a custom Svelte component used as the toast message.

For advanced control or integration, you can use the following hooks:

• useToaster: A composable to interact with the toaster instance.
• useToasterStore: Provides access to the underlying store managing the toast state.

The ToasterProps interface defines the configuration options for the <Toaster /> component. These settings apply globally to all toasts rendered by that instance.

The toast function is the primary way to trigger toast notifications in your application. It can be imported as a named export or as the default export. You can pass options to customize the appearance and behavior of each toast.

import toast from 'svelte-french-toast';

tost('Hello World');

// With options
tost('Success!', { 
  icon: '✅', 
  duration: 3000 
});

To display toasts, you must include the Toaster component in your Svelte component tree (usually at the root level, like App.svelte). The Toaster component manages the rendering and positioning of all active toasts.

<script>
  import { Toaster } from 'svelte-french-toast';
</script>

<Toaster />

The library exports several types to help with TypeScript integration when configuring toasts or building custom components:

• ToastOptions: Configuration for an individual toast.
• ToastPosition: Defines where toasts appear (e.g., top-center, bottom-right).
• ToastType: The category of toast (e.g., success, error).
• ToasterProps: Props available to the Toaster component.
• Renderable: Types that can be rendered as toast content.
• IconTheme: Configuration for toast icons.

The ToastPosition type defines where toasts appear on the screen. It is recommended to use logical positions (start, end) instead of absolute positions (left, right) to ensure automatic adjustment for LTR (Left-to-Right) and RTL (Right-to-Left) text directions.

Available positions:

• Top: top-left, top-center, top-right, top-start, top-end
• Bottom: bottom-left, bottom-center, bottom-right, bottom-start, bottom-end

type ToastPosition =
	| 'top-left'
	| 'top-center'
	| 'top-right'
	| 'bottom-left'
	| 'bottom-center'
	| 'bottom-right'
	| 'top-start'
	| 'top-end'
	| 'bottom-start'
	| 'bottom-end';

If you are using custom icons or themes, you can provide an IconTheme object to specify the color palette used for the toast's icon elements.

export interface IconTheme {
	primary: string;
	secondary: string;
}