Class SfToast

Toast is a small, nonblocking notification pop-up and it is shown to users with readable message content at the bottom of the screen or at a specific target and disappears automatically after a few seconds (time-out) with different animation effects.

Inheritance

System.Object

SfBaseComponent

SfToast

Inherited Members

SfBaseComponent.Dispose()

SfBaseComponent.Dispose(Boolean)

SfBaseComponent.GetEffectivePlatform()

SfBaseComponent.GetMainComponentPlatform()

SfBaseComponent.IsMainLicenseComponent()

SfBaseComponent.LicenseContext

SfBaseComponent.OnObservableChange(String, Object, Boolean, NotifyCollectionChangedEventArgs)

SfBaseComponent.ValidateLicense()

Namespace: Syncfusion.Blazor.Notifications

Assembly: Syncfusion.Blazor.dll

Syntax

public class SfToast : SfBaseComponent

Remarks

The SfToast component provides a flexible notification system that can display various types of messages such as success, error, warning, or information. It supports customizable positioning, animations, and user interactions. The toast can be configured to show progress bars, close buttons, and action buttons for enhanced user experience.

Examples

A simple Toast component implementation.

<SfToast ID="toast" Title="Success" Content="Your operation completed successfully!" Timeout="3000">
    <ToastPosition X="Right" Y="Top"></ToastPosition>
</SfToast>

Constructors

SfToast()

Declaration

public SfToast()

Properties

ChildContent

Sets the content of the Toast.

Declaration

public RenderFragment ChildContent { get; set; }

Property Value

Type
Microsoft.AspNetCore.Components.RenderFragment

Content

Gets or sets the content to be displayed on the Toast. Accepts selectors, string values and HTML elements.

Declaration

public string Content { get; set; }

Property Value

Type	Description
System.String	A `string` value representing the content to be displayed. The default value is `null`.

Remarks

The content can be plain text, HTML markup, or CSS selectors. This property defines the main message that will be shown to the user in the toast notification. If both Content and ContentTemplate are provided, the template takes precedence over the string content. When using HTML content, ensure it is properly sanitized to prevent XSS vulnerabilities.

ContentTemplate

Gets or sets the HTML template that can be displayed as Toast content.

Declaration

public RenderFragment ContentTemplate { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.RenderFragment	A Microsoft.AspNetCore.Components.RenderFragment that defines the template content for the toast. The default value is `null`.

Remarks

When specified, this template will be used to render custom content inside the toast instead of the Content property. This allows for rich HTML content, including other Blazor components, images, buttons, forms, or any complex markup. The template provides significantly more flexibility than the simple string-based Content property, enabling interactive elements and dynamic content rendering. When both ContentTemplate and Content are provided, the template takes precedence and the string content is ignored. The template content is rendered within the toast's content area and inherits the toast's styling context.

CssClass

Gets or sets single/multiple classes (separated by space) to be used for customization of Toast.

Declaration

public string CssClass { get; set; }

Property Value

Type	Description
System.String	A `string` containing CSS class names separated by spaces. The default value is `null`.

Remarks

This property allows you to apply custom CSS styling to the SfToast component. Multiple CSS classes can be specified by separating them with spaces. These classes will be applied to the root element of the toast, enabling complete visual customization including colors, fonts, borders, shadows, and animations. Standard CSS cascading rules apply when combining with built-in toast styles.

EnableRtl

Gets or sets a value indicating whether to enable or disable rendering component in right to left direction.

Declaration

public bool EnableRtl { get; set; }

Property Value

Type	Description
System.Boolean	`true` if the right to left direction is enabled for the component; otherwise, `false`. The default value is `false`.

Remarks

When set to true, the SfToast component will be rendered in right-to-left (RTL) layout, which is suitable for languages that read from right to left such as Arabic, Hebrew, or Persian. This affects the positioning, alignment, animation directions, and progress bar direction of the toast. The RTL mode also influences the placement of icons, close buttons, and action buttons within the toast layout.

ExtendedTimeout

Gets or sets the Toast display time duration after interacting with the Toast.

Declaration

public int ExtendedTimeout { get; set; }

Property Value

Type	Description
System.Int32	An `int` value representing the extended timeout duration in milliseconds. The default value is `1000`.

Remarks

This property defines how long the toast remains visible after user interaction (such as hovering or focusing). When a user interacts with the toast, the normal timeout is extended by this duration, allowing users more time to read or interact with the toast content. This enhances accessibility and user experience by preventing premature dismissal during user engagement. Setting this to 0 disables the extended timeout behavior. The interaction events that trigger this extension include mouse hover, keyboard focus, and touch interactions.

Height

Gets or sets the height of the Toast in pixels/number/percentage. Number value is considered as pixels.

Declaration

public string Height { get; set; }

Property Value

Type	Description
System.String	A `string` value representing the height. The default value is `"auto"`.

Remarks

The height can be specified in various units:

Pixels: "100px" or "100" (numeric value treated as pixels)
Percentage: "50%" (relative to the container height)
Auto: "auto" (automatically adjusts based on content size)

When set to "auto", the toast height will be determined by its content size, providing optimal space utilization. Fixed heights may cause content overflow if insufficient space is provided.

Icon

Gets or sets CSS classes to specify an icon for the Toast which is to be displayed at top left corner of the Toast.

Declaration

public string Icon { get; set; }

Property Value

Type	Description
System.String	A `string` containing CSS icon class names. The default value is `null`.

Remarks

The icon is displayed at the top-left corner of the toast and helps users quickly identify the type of notification. You can use icon fonts like Font Awesome, Material Icons, or Syncfusion's built-in icon library. Common built-in Syncfusion icon classes include:

"e-success" for success messages
"e-error" for error messages
"e-warning" for warning messages
"e-info" for information messages

When null, no icon is displayed, providing more space for the content.

ID

Specifies the unique identifier.

Declaration

public string ID { get; set; }

Property Value

Type
System.String

NewestOnTop

Gets or sets a value that specifies the newly created Toast message display order while multiple toasts are added to page one after another.

Declaration

public bool NewestOnTop { get; set; }

Property Value

Type	Description
System.Boolean	`true` if new toasts should be displayed on top of existing toasts; otherwise, `false`. The default value is `true`.

Remarks

When set to true, newer toast notifications will appear above existing ones, creating a stack where the most recent toast is most visible to users. When set to false, new toasts will be added below existing ones, maintaining chronological order from top to bottom. This property is particularly useful when managing multiple simultaneous notifications and determining which messages should receive priority in user attention. The stacking behavior affects the visual z-index ordering and animation sequence of multiple toasts.

ProgressDirection

Gets or sets the direction for the Toast progress bar.

Declaration

public ProgressDirection ProgressDirection { get; set; }

Property Value

Type	Description
ProgressDirection	A ProgressDirection enumeration value that determines the progress bar direction. The default value is RTL.

Remarks

This property controls the direction in which the progress bar fills as the toast timeout progresses. The progress bar provides visual feedback to users about how much time remains before the toast automatically disappears. Available options include:

RTL - Progress fills from right to left
LTR - Progress fills from left to right

This property only takes effect when ShowProgressBar is set to true. The direction may be automatically adjusted based on the EnableRtl setting for proper localization.

ShowCloseButton

Gets or sets a value indicating whether to show the close button in Toast message to close the Toast.

Declaration

public bool ShowCloseButton { get; set; }

Property Value

Type	Description
System.Boolean	`true` if the close button should be shown; otherwise, `false`. The default value is `false`.

Remarks

When enabled, a close button (×) will be displayed in the top-right corner of the toast, allowing users to manually dismiss the notification before the timeout expires. This improves user control and accessibility by providing an explicit way to dismiss notifications. The close button appearance can be customized using CSS styling. The close button supports keyboard navigation and screen reader accessibility. When clicked, it triggers the close event before removing the toast from the DOM.

ShowProgressBar

Gets or sets a value indicating whether to show the progress bar to denote the Toast message display timeout.

Declaration

public bool ShowProgressBar { get; set; }

Property Value

Type	Description
System.Boolean	`true` if the progress bar should be shown; otherwise, `false`. The default value is `false`.

Remarks

When enabled, a progress bar will be displayed at the bottom of the toast, visually indicating the remaining time before the toast automatically disappears. The progress bar direction is controlled by the ProgressDirection property. This feature helps users understand how much time they have to read or interact with the notification, improving the overall user experience by providing clear visual feedback about the toast's lifecycle. The progress bar animation smoothly decreases as the timeout approaches, and pauses during user interactions when ExtendedTimeout is configured.

Target

Gets or sets the target container where the Toast to be displayed. Based on the target, the positions such as Left, Top will be applied to the Toast.

Declaration

public string Target { get; set; }

Property Value

Type	Description
System.String	A `string` representing the CSS selector or element ID of the target container. The default value is `null`.

Remarks

When null or not specified, the toast will be positioned relative to the document body, allowing full-page positioning. When a specific target is provided (e.g., "#myContainer" or ".toast-container"), the toast will be positioned relative to that element's boundaries. This is useful for constraining toasts to specific areas of the page or creating context-specific notifications within particular sections of the UI. The target element must have CSS positioning (relative, absolute, or fixed) for proper toast positioning. Supported selector formats include element IDs (#elementId), class names (.className), and element tags (div).

Timeout

Gets or sets the Toast display time duration on the page in milliseconds. Once the time expires, Toast message will be removed. Setting 0 as a timeout value displays the Toast on the page until the user closes it manually.

Declaration

public int Timeout { get; set; }

Property Value

Type	Description
System.Int32	An `int` value representing the timeout duration in milliseconds. The default value is `5000`.

Remarks

This property controls how long the toast remains visible before automatically disappearing. Common timeout values and their use cases:

0 - Toast persists until manually closed (useful for critical messages)
3000 - 3 seconds (good for simple success/confirmation messages)
5000 - 5 seconds (default, suitable for most informational content)
10000 - 10 seconds (for longer messages requiring more reading time)

The timeout can be extended when users interact with the toast, based on the ExtendedTimeout property. During user interactions (hover, focus), the timeout timer is paused and resumes after the interaction ends.

Title

Gets or sets the title to be displayed on the Toast. Works only with string values.

Declaration

public string Title { get; set; }

Property Value

Type	Description
System.String	A `string` value representing the title text. The default value is `null`.

Remarks

The title appears at the top of the toast in a larger, bold font to provide a quick summary or heading for the notification. It's displayed above the main content and helps users quickly identify the purpose or category of the message. When null or empty, no title section is rendered in the toast, providing more space for the main content. The title supports plain text only and does not render HTML markup. For complex title formatting, consider using custom CSS classes via the CssClass property.

Width

Gets or sets the width of the Toast in pixels/numbers/percentage. Number value is considered as pixels. In mobile devices, default width is considered as 100%.

Declaration

public string Width { get; set; }

Property Value

Type	Description
System.String	A `string` value representing the width. The default value is `"300px"`.

Remarks

The width can be specified in various units:

Pixels: "300px" or "300" (numeric value treated as pixels)
Percentage: "80%" (relative to the container width)
Auto: "auto" (adjusts based on content width with constraints)
Viewport units: "50vw" (relative to viewport width)

On mobile devices, the width automatically defaults to "100%" for better responsiveness, ensuring the toast spans the full width of the screen for optimal mobile user experience and touch interaction. The responsive behavior can be customized using CSS media queries in conjunction with the CssClass property.

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration

protected override void BuildRenderTree(RenderTreeBuilder __builder)

Parameters

Type	Name	Description
Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder	__builder

OnAfterRenderAsync(Boolean)

Method invoked after the component has rendered, handling first-render specific logic and event notifications.

Declaration

protected override Task OnAfterRenderAsync(bool firstRender)

Parameters

Type	Name	Description
System.Boolean	firstRender	Set to `true` if this is the first time OnAfterRenderAsync has been invoked on this component instance; otherwise `false`.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task representing any asynchronous operation.

Overrides

SfBaseComponent.OnAfterRenderAsync(Boolean)

Remarks

This method ensures that the Created event delegate is invoked only during the first render cycle, providing a reliable hook for components that need to perform actions after the initial DOM rendering is complete.

The base implementation is always called first to maintain the proper component lifecycle chain, followed by first-render specific logic execution.

OnInitializedAsync()

Method invoked when the component is ready to start, responsible for initializing the Toast component's core properties and configuration.

Declaration

protected override Task OnInitializedAsync()

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task representing any asynchronous operation.

Overrides

SfBaseComponent.OnInitializedAsync()

Remarks

This method performs the following initialization steps:

Generates or validates the component ID
Sets the target element (defaults to document body if not specified)
Configures positioning strategy (fixed for body target, absolute for custom targets)
Applies RTL styling if enabled globally or locally
Updates position and animation settings
Handles full-width configuration when width is set to 100%
Registers script modules and handles static rendering scenarios

Any exceptions during initialization are logged to the console and re-thrown to ensure proper error handling by the caller.

ShowAsync(ToastModel)

Shows a Toast element on the document with the specified configuration and position.

Declaration

public Task ShowAsync(ToastModel toastModel = null)

Parameters

Type	Name	Description
ToastModel	toastModel	An optional ToastModel that specifies the configuration for the Toast element to be displayed. If `null`, the default Toast configuration will be used.

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task representing the asynchronous show operation.

Remarks

This method displays a Toast notification on the screen with the specified or default configuration. When a ToastModel is provided, the Toast will be displayed with the properties defined in that model. If no model is provided (null), the Toast will use the default configuration settings. The Toast will appear with the configured animation effects and will trigger the appropriate show events. The position of the Toast is determined by the relative positioning settings configured in the component or model.

Examples

<SfToast @ref="toastObj">
    <ToastPosition X="Right" Y="Top"></ToastPosition>
</SfToast>

@code {
    SfToast toastObj;

    private async Task ShowDefaultToast()
    {
        await toastObj.ShowAsync();
    }

    private async Task ShowCustomToast()
    {
        ToastModel model = new ToastModel
        {
            Title = "Success",
            Content = "Your changes have been saved successfully!",
            CssClass = "e-toast-success",
            Timeout = 5000
        };
        await toastObj.ShowAsync(model);
    }
}