Class SfTooltip

The SfTooltip component displays a pop-up containing information or a message when you hover, click, focus, or touch an element.

Inheritance
System.Object
SfBaseComponent
SfTooltip
Inherited Members
Namespace: Syncfusion.Blazor.Popups
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfTooltip : SfBaseComponent
Remarks

The SfTooltip component provides a highly customizable tooltip experience with support for various triggers, animations, positioning, and styling options. It can be used to display contextual information, form validation messages, or help text for UI elements. The component supports sticky tooltips, mouse trailing, collision detection, and rich content templates.

Examples

Basic usage of the SfTooltip component:

<SfTooltip Target="#target" Content="This is a tooltip">
    <div id="target">Hover over me</div>
</SfTooltip>

Basic tooltip implementation:

<SfTooltip Content="Click to save the document">
    <button>Save</button>
</SfTooltip>
<SfTooltip Content="Let's go green to save the planet!!">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

A simple Tooltip component.

<SfTooltip Content="This is a tooltip">
    <button>Hover me</button>
</SfTooltip>

Constructors

SfTooltip()

Declaration
public SfTooltip()

Properties

Animation

Gets or sets the animation settings for the opening and closing of the Tooltip.

Declaration
public AnimationModel Animation { get; set; }
Property Value
Type
AnimationModel
Remarks

The animation property allows you to customize the animation of the Tooltip component, including the delay, duration, and various other effects of your choice. You can set the same or different animation options to the Tooltip when it is in the open or close state.

Examples
<SfTooltip Content="Let's go green to save the planet!!" Animation="@Animation">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>
@code {
 public AnimationModel Animation { get; set; } = new AnimationModel
{
   Open = new TooltipAnimationSettings {Delay = 0, Duration = 500, Effect = Effect.ZoomIn },
   Close = new TooltipAnimationSettings{Delay=0,Duration=500,Effect=Effect.ZoomOut}
};
}

ChildContent

Specifies the content that has to be rendered.

Declaration
public RenderFragment ChildContent { get; set; }
Property Value
Type
Microsoft.AspNetCore.Components.RenderFragment

Closed

Gets or sets an event callback that is raised when the Tooltip component is closed.

Declaration
public EventCallback<TooltipEventArgs> Closed { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<TooltipEventArgs>

An Microsoft.AspNetCore.Components.EventCallback<> of type TooltipEventArgs that is invoked when the Tooltip is closed.
Remarks

This event is triggered after the Tooltip has been completely closed and removed from view. It is useful for performing additional actions when the Tooltip is closed, such as updating the UI, performing cleanup tasks, or logging user interactions. The event callback function receives a TooltipEventArgs parameter, which provides detailed information about the Tooltip that was closed, including the target element and event details.

Examples
<SfTooltip Closed="OnTooltipClosed">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipClosed(TooltipEventArgs args)
    {
        // Perform cleanup or update UI
        Console.WriteLine("Tooltip closed");
    }
}

CloseDelay

Gets or sets the delay in milliseconds before the Tooltip closes.

Declaration
public double CloseDelay { get; set; }
Property Value
Type Description
System.Double

Accepts a double value representing the delay in milliseconds. The default value is 0.
Remarks

The CloseDelay property is used to specify the delay in milliseconds before the Tooltip closes. If no delay is needed, the default value of 0 can be used.

Examples
<SfTooltip Content="Let's go green to save the planet!!" CloseDelay="2000">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

Container

Gets or sets the container element in which the Tooltip's pop-up will be appended.

Declaration
public string Container { get; set; }
Property Value
Type Description
System.String

A string value that represents the container element selector. The default value is body.
Remarks

The Container property specifies where the Tooltip element should be rendered in the DOM. By default, tooltips are appended to the document body, but you can specify a different container using a CSS selector. This is useful for controlling the stacking context and ensuring proper positioning within specific layout containers.

Examples
<div class="parent">
<SfTooltip Content="Let's go green to save the planet!!" Container=".parent">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>
</div>

Content

Gets or sets the content of the Tooltip component.

Declaration
public string Content { get; set; }
Property Value
Type Description
System.String

Accepts a string value representing the content of the Tooltip component.
Remarks

The Content property is used to specify the content of the Tooltip component as a string element.

Examples
<SfTooltip Content="Let's go green to save the planet!!">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

ContentTemplate

Gets or sets the template that defines the content of the component.

Declaration
public RenderFragment ContentTemplate { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.RenderFragment

The default value is null.
Remarks

The ContentTemplate is a RenderFragment that allows users to customize the appearance and content of the component. This property can be used to define custom HTML or Razor markup to be rendered as the content of the component.

Created

Gets or sets an event callback that is raised after the Tooltip component is created.

Declaration
public EventCallback<object> Created { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>

An Microsoft.AspNetCore.Components.EventCallback<> of type System.Object that is invoked after the Tooltip component is successfully created.
Remarks

This event is triggered after the Tooltip component has been fully initialized and is ready for use. It provides an opportunity to perform post-initialization tasks, such as setting up additional event handlers, applying custom configurations, or integrating with other components. The event callback receives a generic System.Object parameter that contains component creation details. This is typically used for component lifecycle management and integration with external libraries or frameworks.

Examples
<SfTooltip Created="OnTooltipCreated">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipCreated(object args)
    {
        // Perform post-creation tasks
        Console.WriteLine("Tooltip component created successfully");
    }
}

CssClass

Gets or sets the CSS classes to be applied to the Tooltip component.

Declaration
public string CssClass { get; set; }
Property Value
Type Description
System.String

Accepts a CSS class string separated by space to customize the appearance of the component.
Remarks

The CssClass property is used to apply custom CSS class names that define specific user-defined styles and themes to be applied to the Tooltip element. Multiple class names can be specified by separating them with a space.

Examples
<SfTooltip Content="Let's go green to save the planet!!" CssClass="customtip">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

Destroyed

Gets or sets an event callback that is raised when the Tooltip component is destroyed.

Declaration
public EventCallback<object> Destroyed { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>

An Microsoft.AspNetCore.Components.EventCallback<> of type System.Object that is invoked when the Tooltip component is being destroyed.
Remarks

This event is triggered when the Tooltip component is being disposed and removed from the component tree. It provides an opportunity to perform cleanup tasks, such as removing event handlers, clearing cached data, or disposing of resources. The event callback receives a generic System.Object parameter that contains component destruction details. This is essential for proper memory management and preventing memory leaks in complex applications. Use this event to ensure that all resources associated with the Tooltip are properly cleaned up before the component is removed.

Examples
<SfTooltip Destroyed="OnTooltipDestroyed">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipDestroyed(object args)
    {
        // Perform cleanup tasks
        Console.WriteLine("Tooltip component destroyed");
    }
}

EnableRtl

Gets or sets a value indicating whether to enable or disable the rendering of the component in right-to-left (RTL) direction.

Declaration
public bool EnableRtl { get; set; }
Property Value
Type Description
System.Boolean

true, if the right to left direction can be enabled; Otherwise, false. The default value is false.
Remarks

The EnableRtl property is used to render the Tooltip component from right to left direction.

Height

Gets or sets the height of the Tooltip component.

Declaration
public string Height { get; set; }
Property Value
Type Description
System.String

Accepts the string value. The default value is auto.
Remarks

The Height property is used to specify the height of the Tooltip component. If no height is specified, the Tooltip height will be set based on its content. When the content of the Tooltip exceeds the height value, the scroll mode will be enabled. The value can be any valid CSS height value, such as "100px" or "50%".

Examples
<SfTooltip Content="Let's go green to save the planet!!" Height="40px">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

HtmlAttributes

Gets or sets a collection of additional attributes that will applied to the tooltip element.

Declaration
public Dictionary<string, object> HtmlAttributes { get; set; }
Property Value
Type
System.Collections.Generic.Dictionary<System.String, System.Object>
Remarks

Additional attributes can be added by specifying as inline attributes or by specifying @attributes directive.

Examples

In the below code example, tooltip width has been specified as style attribute in SfTooltip tag directive.

<SfTooltip Content="Let's go green to save the planet!!" style="width:100px">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

ijsRuntime

Declaration
protected IJSRuntime ijsRuntime { get; set; }
Property Value
Type
Microsoft.JSInterop.IJSRuntime

IsSticky

Gets or sets a value indicating whether the Tooltip should be displayed in an open state until it is closed manually.

Declaration
public bool IsSticky { get; set; }
Property Value
Type Description
System.Boolean

true, if the Tooltip should be displayed in an open state until it is closed manually. Otherwise, false. The default value is false.
Remarks

The IsSticky property is used to set the behavior of the Tooltip when it is displayed. If the value is set to true, the Tooltip will be displayed in an open state until it is closed manually, regardless of the user interaction that triggered the Tooltip. If the value is set to false, the Tooltip will be displayed for a specified duration based on the Animation property and then automatically closed.

MouseTrail

Gets or sets a value indicating whether the Tooltip should follow the mouse pointer as it moves over the specified target element.

Declaration
public bool MouseTrail { get; set; }
Property Value
Type Description
System.Boolean

true, if the Tooltip should follow the mouse pointer when it moves over the specific target. Otherwise, false. The default value is false.
Remarks

The MouseTrail property enables the Tooltip to dynamically follow the mouse cursor position when the user moves the mouse over the target element. When enabled, the Tooltip position will continuously update based on the mouse coordinates, creating a trailing effect.

OffsetX

Gets or sets the X-axis offset between the target and Tooltip element.

Declaration
public double OffsetX { get; set; }
Property Value
Type Description
System.Double

A double value representing the space between the target and Tooltip element in X-axis. The default value is 0.
Remarks

The OffsetX property allows you to adjust the horizontal position of the Tooltip relative to its target element. Positive values move the Tooltip to the right, while negative values move it to the left. This offset is applied in addition to the base position determined by the Position property.

Examples
<SfTooltip Content="Let's go green to save the planet!!" OffsetX="20">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

OffsetY

Gets or sets the Y-axis offset between the target and Tooltip element.

Declaration
public double OffsetY { get; set; }
Property Value
Type Description
System.Double

Accepts a double value representing the space between the target and Tooltip element in the Y-axis. The default value is 0.
Remarks

The OffsetY property allows you to adjust the vertical position of the Tooltip relative to its target element. Positive values move the Tooltip downward, while negative values move it upward. This offset is applied in addition to the base position determined by the Position property.

Examples
<SfTooltip Content="Let's go green to save the planet!!" OffsetY="70">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

OnClose

Gets or sets an event callback that is raised before the Tooltip hides from the screen.

Declaration
public EventCallback<TooltipEventArgs> OnClose { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<TooltipEventArgs>

An Microsoft.AspNetCore.Components.EventCallback<> of type TooltipEventArgs that is invoked before the Tooltip is hidden.
Remarks

This event is triggered before the Tooltip starts the hiding process, providing an opportunity to perform validation or cleanup operations. It is useful for performing additional actions before the Tooltip is closed, such as updating the UI, validating user input, or saving data. The event callback function receives a TooltipEventArgs parameter, which provides information about the Tooltip that is about to be closed. To prevent the Tooltip from closing, set the Cancel property of the TooltipEventArgs parameter to true. This cancellation capability makes this event ideal for implementing custom validation logic or user confirmation dialogs.

Examples
<SfTooltip OnClose="OnTooltipClose">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipClose(TooltipEventArgs args)
    {
        // Validate or prevent closing
        if (someCondition)
        {
            args.Cancel = true; // Prevent tooltip from closing
        }
    }
}

OnCollision

Gets or sets an event callback that is raised for every collision fit calculation.

Declaration
public EventCallback<TooltipEventArgs> OnCollision { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<TooltipEventArgs>

An Microsoft.AspNetCore.Components.EventCallback<> of type TooltipEventArgs that is invoked during collision detection calculations.
Remarks

This event is triggered whenever the Tooltip component performs collision detection to determine the optimal positioning on the screen. It is useful for fine-tuning the placement of the Tooltip on the screen and avoiding overlaps with other UI elements or viewport boundaries. The event callback function receives a TooltipEventArgs parameter, which provides comprehensive information about the Tooltip and its placement calculations. The TooltipEventArgs parameter includes the target element and collision information object, which describe the Tooltip's current position, collision detection results, and suggested positioning adjustments. This event allows for custom collision handling logic and dynamic positioning strategies based on the current layout and available screen space.

Examples
<SfTooltip OnCollision="OnTooltipCollision">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipCollision(TooltipEventArgs args)
    {
        // Handle collision and adjust positioning
        Console.WriteLine($"Collision detected at position: {args.CollisionInfo}");
    }
}

OnOpen

Gets or sets an event callback that is raised before the Tooltip is displayed over the target element.

Declaration
public EventCallback<TooltipEventArgs> OnOpen { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<TooltipEventArgs>

An Microsoft.AspNetCore.Components.EventCallback<> of type TooltipEventArgs that is invoked before the Tooltip is displayed.
Remarks

This event is triggered before the Tooltip becomes visible, providing an opportunity to customize its appearance, content, or behavior. It is useful for dynamically modifying the Tooltip's appearance or behavior before it is displayed, such as setting custom content, applying conditional styling, or performing pre-display validation. The event callback function receives a TooltipEventArgs parameter, which provides comprehensive information about the Tooltip and its target element. The TooltipEventArgs parameter includes the target element and an optional Cancel property, which can be set to true to prevent the Tooltip from being displayed. This cancellation capability allows for conditional Tooltip display based on dynamic conditions or user permissions.

Examples
<SfTooltip OnOpen="OnTooltipOpen">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipOpen(TooltipEventArgs args)
    {
        // Customize tooltip before display
        if (!userHasPermission)
        {
            args.Cancel = true; // Prevent tooltip from showing
        }
    }
}

OnRender

Gets or sets an event callback that is raised before the Tooltip and its contents will be added to the DOM.

Declaration
public EventCallback<TooltipEventArgs> OnRender { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<TooltipEventArgs>

An Microsoft.AspNetCore.Components.EventCallback<> of type TooltipEventArgs that is invoked before the Tooltip is rendered to the DOM.
Remarks

This event is triggered before the Tooltip element and its contents are created and added to the DOM, providing the earliest opportunity for customization. When the Cancel property of the TooltipEventArgs parameter is set to true, the Tooltip can be prevented from rendering on the page. This event is primarily used to customize the Tooltip before it appears on the screen, such as loading dynamic content, applying custom styling, or setting animation effects. It is ideal for scenarios where you need to load AJAX content, apply conditional formatting, or perform any DOM manipulation before the Tooltip becomes visible. The event provides full control over the Tooltip's initial state and allows for dynamic content generation based on the target element or application state.

Examples
<SfTooltip OnRender="OnTooltipRender">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipRender(TooltipEventArgs args)
    {
        // Load dynamic content or customize before rendering
        if (needsAjaxContent)
        {
            // Load AJAX content
            args.Content = GetDynamicContent();
        }
    }
}

OpenDelay

Gets or sets the delay time in milliseconds for opening the Tooltip after the user hovers over the target element.

Declaration
public double OpenDelay { get; set; }
Property Value
Type Description
System.Double

A double value representing the delay time in milliseconds. The default value is 0, which means that the Tooltip opens immediately after the user hovers over the target element.
Remarks

The OpenDelay property is useful for preventing the Tooltip from appearing too quickly when users move their mouse over elements. By setting a delay, you can improve the user experience by avoiding tooltips that flash or appear unintentionally during quick mouse movements.

Examples
<SfTooltip Content="Let's go green to save the planet!!" OpenDelay="2000">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

Opened

Gets or sets an event callback that is raised when the Tooltip component is opened.

Declaration
public EventCallback<TooltipEventArgs> Opened { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<TooltipEventArgs>

An Microsoft.AspNetCore.Components.EventCallback<> of type TooltipEventArgs that is invoked when the Tooltip is opened.
Remarks

This event is triggered after the Tooltip has been successfully opened and is visible to the user. It is useful for performing additional actions when the Tooltip is opened, such as updating the UI, tracking user interactions, or initializing dynamic content. The event callback function receives a TooltipEventArgs parameter, which provides detailed information about the Tooltip that was opened, including the target element and event context.

Examples
<SfTooltip Opened="OnTooltipOpened">
    <div>Hover over me</div>
</SfTooltip>

@code {
    private void OnTooltipOpened(TooltipEventArgs args)
    {
        // Track user interaction or update UI
        Console.WriteLine("Tooltip opened");
    }
}

OpensOn

Gets or sets the type of open mode to display the Tooltip content. The available open modes are Auto, Hover, Click, Focus, and Custom.

Declaration
public string OpensOn { get; set; }
Property Value
Type Description
System.String

Accepts a string value that specifies when the Tooltip should be displayed. The default value is Auto.
Remarks

The OpensOn property determines the event that triggers the Tooltip to appear. The supported values are:

  • Auto: Automatically detects the appropriate trigger event based on the target element
  • Hover: Tooltip appears when the mouse hovers over the target element
  • Click: Tooltip appears when the target element is clicked
  • Focus: Tooltip appears when the target element receives focus
  • Custom: Tooltip is triggered programmatically using custom events
Examples
<SfTooltip Content="Let's go green to save the planet!!" OpensOn="Click">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

Position

Gets or sets the position of the Tooltip element with respect to the Target element.

Declaration
public Position Position { get; set; }
Property Value
Type Description
Position

A value of the Position enumeration that specifies the position of Tooltip element. The default value is TopCenter.
Remarks

The Position property determines where the Tooltip will appear relative to its target element. The component automatically adjusts the position if there isn't enough space in the specified direction, ensuring the Tooltip remains visible within the viewport boundaries.

Examples
<SfTooltip Content="Let's go green to save the planet!!" Position=Position.LeftBottom>
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

ShowTipPointer

Gets or sets a value indicating whether to show or hide the tip pointer of the Tooltip.

Declaration
public bool ShowTipPointer { get; set; }
Property Value
Type Description
System.Boolean

true, if the tip pointer should be shown. Otherwise, false. The default value is true.
Remarks

The ShowTipPointer property controls the visibility of the small arrow or pointer that connects the Tooltip to its target element. The tip pointer provides a visual connection between the Tooltip and the element that triggered it, improving the user experience. When set to false, the Tooltip will appear without the pointing arrow.

Target

Gets or sets the target selector where the Tooltip needs to be displayed.

Declaration
public string Target { get; set; }
Property Value
Type Description
System.String

A string value representing the target selector. The target element is considered as the parent container. The default value is null.
Remarks

The Target property specifies the CSS selector for the element(s) that should trigger the Tooltip. If not specified, the Tooltip will be applied to its immediate child content. You can use any valid CSS selector such as element names, class names, IDs, or attribute selectors.

Examples
<SfTooltip Content="Let's go green to save the planet!!" Target="#btn" >
 <SfButton ID="btn" Content="Show Tooltip"></SfButton>
</SfTooltip>

TargetContainer

Gets or sets the CSS selector for a container where target elements will automatically have tooltips applied.

Declaration
public string TargetContainer { get; set; }
Property Value
Type Description
System.String

A string representing a CSS selector for the container. The default value is null. If the target elements reside within a specific container, provide its selector as the value; otherwise, tooltip element will be considered as target container.
Remarks

Use this property to attach tooltips to multiple target elements within a specific container or across the entire body element. It facilitates the automatic binding of tooltips to newly added elements matching the specified target selector within the defined container.

TipPointerPosition

Gets or sets the position of the tip pointer on the tooltip. The available options are Auto, Start, Middle, and End. When set to auto, the tip pointer gets auto adjusted within the space of the target's length and does not point outside.

Declaration
public TipPointerPosition TipPointerPosition { get; set; }
Property Value
Type Description
TipPointerPosition

A value of the TipPointerPosition enumeration that specifies the position of the tip pointer. The default value is Auto.
Remarks

The TipPointerPosition property controls where the tip pointer is positioned along the edge of the Tooltip. When set to Auto, the component automatically adjusts the pointer position to ensure it points toward the target element and remains within the bounds of the Tooltip. Manual positioning options (Start, Middle, End) allow for precise control over the pointer placement regardless of the target element's position.

Examples
<SfTooltip Content="Let's go green to save the planet!!" TipPointerPosition=TipPointerPosition.End>
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

Width

Gets or sets the width of the Tooltip component which accepts a string value.

Declaration
public string Width { get; set; }
Property Value
Type Description
System.String

Accepts the string value.The default value is auto.
Remarks

When set to auto, the Tooltip width gets auto adjusted to display its content within the viewable screen.

Examples
<SfTooltip Content="Let's go green to save the planet!!" Width="100px">
 <SfButton Content="Show Tooltip"></SfButton>
</SfTooltip>

WindowCollision

Gets or sets a value indicating whether to set the collision target element as the page viewport (window) or the Tooltip element, when using the target.

Declaration
public bool WindowCollision { get; set; }
Property Value
Type Description
System.Boolean

true, if the window collision can be enabled; otherwise, false. The default value is false.
Remarks

The WindowCollision property is used to enable or disable the collision calculation between the target elements and viewport (window) instead of the Tooltip element. If the value is set to true, the collision will be calculated between the target and the viewport (window). Otherwise, the collision will be calculated between the target and the Tooltip element.

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder __builder

CloseAsync(TooltipAnimationSettings)

Asynchronously closes the Tooltip with customizable animation settings for the closing transition.

Declaration
public Task CloseAsync(TooltipAnimationSettings animation = null)
Parameters
Type Name Description
TooltipAnimationSettings animation

The animation configuration to apply during the tooltip closing transition. When null, uses the default "Close" animation configuration from the Animation property.
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task representing the asynchronous operation of closing the tooltip with the specified animation settings.
Remarks

This method programmatically hides the currently visible tooltip with precise control over the closing animation behavior. The method ensures smooth visual transitions and proper cleanup of tooltip resources through JavaScript interop communication.

The animation parameter provides comprehensive control over the closing transition, including effect type, duration, easing function, and delay settings. When no custom animation is specified, the component uses the default closing animation configured in the Animation property.

The method includes validation to ensure the component's JavaScript runtime is properly initialized before executing the tooltip hiding logic. This prevents potential runtime errors when the component is not fully loaded or has been disposed.

Examples

Closing a tooltip with custom animation settings.

// Close tooltip with custom fade-out animation
var customCloseAnimation = new TooltipAnimationSettings { Effect = "FadeOut", Duration = 500 };
await tooltipComponent.CloseAsync(customCloseAnimation);

// Close tooltip with default animation
await tooltipComponent.CloseAsync();

OnAfterRenderAsync(Boolean)

Asynchronously executes logic after the component has rendered.

Declaration
protected override Task OnAfterRenderAsync(bool firstRender)
Parameters
Type Name Description
System.Boolean firstRender

True if this is the first time the component has rendered; otherwise, false.
Returns
Type Description
System.Threading.Tasks.Task

A task that represents the asynchronous post-render operation.
Overrides
Remarks

This method handles post-render operations including:

  • Invoking the Created event callback on first render
  • Updating tooltip content after rendering
  • Ensuring proper synchronization between the rendered DOM and component state
The firstRender parameter is used to determine if initialization-specific logic should be executed.

OnInitializedAsync()

Asynchronously initializes the SfTooltip component.

Declaration
protected override Task OnInitializedAsync()
Returns
Type Description
System.Threading.Tasks.Task

A task that represents the asynchronous initialization operation.
Overrides
Remarks

This method performs the following initialization tasks:

  • Generates a unique ID if none is provided
  • Initializes all internal property values from component parameters
  • Sets up HTML attributes and CSS classes
  • Configures the required script modules for tooltip functionality
The method ensures that all tooltip properties are properly initialized before the component is rendered.

OnParametersSetAsync()

Asynchronously handles parameter changes in the SfTooltip component.

Declaration
protected override Task OnParametersSetAsync()
Returns
Type Description
System.Threading.Tasks.Task

A task that represents the asynchronous parameter update operation.
Remarks

This method is called whenever component parameters are updated. It performs the following operations:

  • Compares new parameter values with existing values
  • Tracks property changes for efficient updates
  • Updates the JavaScript component if the component is already rendered
  • Ensures proper synchronization between Blazor properties and JavaScript tooltip instance
The method uses the NotifyPropertyChanges mechanism to optimize updates by only processing changed properties.

OpenAsync(Nullable<ElementReference>, TooltipAnimationSettings)

Asynchronously opens the Tooltip with customizable animation settings and target element.

Declaration
public Task OpenAsync(Nullable<ElementReference> element = null, TooltipAnimationSettings animation = null)
Parameters
Type Name Description
System.Nullable<Microsoft.AspNetCore.Components.ElementReference> element

The target element reference where the Tooltip should be displayed. When null, uses the default tooltip element configured for the component.
TooltipAnimationSettings animation

The animation settings to apply during the tooltip opening transition. When null, uses the default "Open" animation configuration from the Animation property.
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task representing the asynchronous operation of opening the tooltip with the specified settings.
Remarks

This method programmatically displays the tooltip with precise control over the target element and animation behavior. The method ensures proper JavaScript interop communication to render the tooltip with optimal positioning and visual effects.

When specifying a custom target element, the tooltip will be positioned relative to that element using the configured positioning logic. The animation parameter allows for fine-grained control over the opening transition, including duration, easing, and effects.

The method performs validation to ensure the component's JavaScript runtime is properly initialized before executing the tooltip display logic. If the script is not rendered, the operation will be deferred until the component is fully loaded.

Examples

Opening a tooltip with custom animation on a specific element.

// Open tooltip on a specific button element with fade-in animation
var customAnimation = new TooltipAnimationSettings { Effect = "FadeIn", Duration = 300 };
await tooltipComponent.OpenAsync(buttonElement, customAnimation);

// Open tooltip with default settings
await tooltipComponent.OpenAsync();

PreventRender(Boolean)

Controls the re-rendering behavior of the Tooltip component.

Declaration
public void PreventRender(bool preventRender = true)
Parameters
Type Name Description
System.Boolean preventRender

Optional. Determines whether the component should be prevented from re-rendering. Default value is true.
Remarks

This method internally sets the value to be returned by the ShouldRender method. By default, this method prevents the component from rendering. To enable rendering again, set preventRender to false.

RefreshAsync()

Asynchronously refreshes the entire Tooltip component to synchronize with dynamic DOM changes and target element updates.

Declaration
public Task RefreshAsync()
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task representing the asynchronous operation of refreshing the tooltip component's configuration and bindings.
Remarks

This method performs a comprehensive refresh of the tooltip component, rebuilding its internal state to accommodate dynamic changes in the target elements or DOM structure. It is particularly useful when target elements are added, removed, or modified after the initial component initialization.

The refresh operation re-evaluates all tooltip configurations, including target selectors, positioning logic, content bindings, and event handlers. This ensures that the tooltip maintains proper functionality even when the underlying DOM structure changes dynamically through JavaScript manipulation or framework updates.

The method communicates with the JavaScript runtime to rebuild the tooltip's internal data structures and re-establish proper event bindings with updated target elements. This operation is essential for maintaining tooltip functionality in single-page applications where DOM content changes frequently.

Examples

Refreshing the tooltip after dynamic content changes.

// After adding new elements dynamically to the page
await AddNewElementsToPage();
await tooltipComponent.RefreshAsync();

// After modifying existing target elements
await UpdateTargetElementAttributes();
await tooltipComponent.RefreshAsync();

RefreshPositionAsync(Nullable<ElementReference>)

Asynchronously recalculates and updates the Tooltip's position based on the current location and dimensions of the target element.

Declaration
public Task RefreshPositionAsync(Nullable<ElementReference> target = null)
Parameters
Type Name Description
System.Nullable<Microsoft.AspNetCore.Components.ElementReference> target

The target element reference for position calculation. When null, uses the default target element configured through the Target property.
Returns
Type Description
System.Threading.Tasks.Task

A System.Threading.Tasks.Task representing the asynchronous operation of recalculating and updating the tooltip's position.
Remarks

This method performs precise position recalculation for scenarios where the target element's position, size, or visibility has changed after the tooltip was initially positioned. It is essential for maintaining proper tooltip alignment in dynamic layouts, responsive designs, or when target elements are moved programmatically.

The position refresh operation considers all positioning constraints including collision detection, viewport boundaries, offset values, and preferred positioning strategies. The method ensures optimal tooltip placement while respecting the configured positioning preferences and avoiding content overflow or clipping.

When a specific target element is provided, the method calculates the position relative to that element's current bounding rectangle. If no target is specified, the method uses the default target configuration, making it suitable for both targeted and general position updates.

This operation is particularly valuable in scenarios such as window resizing, scrolling, element animations, or dynamic content changes that affect element positioning.

Examples

Refreshing tooltip position after layout changes.

// Refresh position after window resize
window.addEventListener("resize", async () => {
    await tooltipComponent.RefreshPositionAsync();
});

// Refresh position for a specific target element after animation
await AnimateElement(targetElement);
await tooltipComponent.RefreshPositionAsync(targetElement);

// Refresh position after scrolling or layout changes
await tooltipComponent.RefreshPositionAsync();

ShouldRender()

Determines whether the component should re-render.

Declaration
protected override bool ShouldRender()
Returns
Type Description
System.Boolean

True if the component should re-render; otherwise, false.
Remarks

This method controls the rendering behavior of the SfTooltip component by:

  • Reading the current shouldRender flag value
  • Resetting the shouldRender flag to true for the next render cycle
  • Returning the previous flag value to determine if rendering should occur
This mechanism allows for fine-grained control over when the component updates, optimizing performance by preventing unnecessary re-renders when component state hasn't meaningfully changed.