LgLoaderView

LgLoaderView displays a loading state then automatically replaces the loader with the final content. It covers indeterminate loading, determinate progressions with Lagoon.Helpers.Progress, errors, cancellation, and restart.

<LgLoaderView IsLoading="@IsLoading" Label="#LoadingOrders">
    @("#OrdersLoaded".Translate())
</LgLoaderView>

• Namespace : Lagoon.UI.Components
• Inherits from : LgComponentBase
• NuGet package : Lagoon.UI

Usage

Demonstration

Try this component in the Lagoon showcase.

Indeterminate loading

Use IsLoading to display the loader while processing is not complete. ChildContent is rendered only after loading.

Choose the animation

Without progress, LgLoaderView displays the application spinner, the same one as on the startup screen. It is chosen in the client's main.scss: see Loading spinner.

OrdersLoaderPage.razor

<LgLoaderView IsLoading="@IsLoading" Label="#LoadingOrders">
    @("#OrdersLoaded".Translate())
</LgLoaderView>

<LgButton Text="#ReloadOrders" OnClick="ReloadOrdersAsync" />

OrdersLoaderPage.razor.cs

public partial class OrdersLoaderPage : LgPage
{
    // Indicates whether data is being loaded.
    private bool IsLoading { get; set; } = true;

    // Starts a reload and lets LgLoaderView display the waiting state.
    private async Task ReloadOrdersAsync(ActionEventArgs args)
    {
        IsLoading = true;
        await Task.Delay(1000, args.CancellationToken);
        IsLoading = false;
    }
}

Determinate loading with Progress

Pass an instance of Lagoon.Helpers.Progress for the loader to automatically track Position, StartPosition, EndPosition, and Message.

ImportLoaderPage.razor

<LgLoaderView Progress="@ImportProgress" ProgressType="ProgressType.Circle">
    @("#ImportCompleted".Translate())
</LgLoaderView>

<LgButton Text="#StartImport" OnClick="StartImportAsync" />

ImportLoaderPage.razor.cs

public partial class ImportLoaderPage : LgPage
{
    // Progress shared with LgLoaderView; it triggers component refresh.
    private Progress ImportProgress { get; } = new(100, "#ImportStarting");

    // Simulates an import and publishes each step in the Progress object.
    private async Task StartImportAsync(ActionEventArgs args)
    {
        ImportProgress.Reset(100, "#ImportStarting");
        for (int i = 0; i <= 100; i++)
        {
            ImportProgress.Report(i, "#ImportRunning");
            await Task.Delay(25, args.CancellationToken);
        }
    }
}

Progress bar or circle

ProgressType chooses the determinate rendering: circle by default or horizontal bar. In bar mode, LgLoaderView renders an LgProgress.

ArchiveLoaderPage.razor

<LgLoaderView Progress="@ArchiveProgress" ProgressType="ProgressType.Bar">
    @("#ArchiveCompleted".Translate())
</LgLoaderView>

ArchiveLoaderPage.razor.cs

public partial class ArchiveLoaderPage : LgPage
{
    // Progress used to display a horizontal bar in the loader.
    private Progress ArchiveProgress { get; } = new(50, "#ArchiveStarting");
}

Custom loader rendering

CustomTemplate receives the Progress instance and replaces the default rendering during loading.

CustomLoaderPage.razor

<LgLoaderView IsLoading="@IsLoading">
    <CustomTemplate Context="progress">
        <LgIcon IconName="@IconNames.Loading" CssClass="custom-loader-icon" />
        <LgLabel Text="@(progress?.Message)" />
    </CustomTemplate>
    <ChildContent>
        @("#CustomLoadingCompleted".Translate())
    </ChildContent>
</LgLoaderView>

CustomLoaderPage.razor.cs

public partial class CustomLoaderPage : LgPage
{
    // Drives the display of custom rendering while waiting.
    private bool IsLoading { get; set; } = true;
}

Error, cancellation, and restart

IsError displays an error message. OnActionCancellation adds a cancellation button; OnActionRestart adds a restart button after cancellation or error.

CancelableLoaderPage.razor

<LgLoaderView IsLoading="@IsLoading"
              IsError="@IsError"
              ErrorTitle="#LoadingErrorTitle"
              ErrorDescription="#LoadingErrorDescription"
              CancelDescription="#LoadingCancelled"
              OnActionCancellation="CancelLoadingAsync"
              OnActionRestart="RestartLoadingAsync">
    @("#LoadingCompleted".Translate())
</LgLoaderView>

CancelableLoaderPage.razor.cs

public partial class CancelableLoaderPage : LgPage
{
    // Indicates whether processing is still ongoing.
    private bool IsLoading { get; set; } = true;

    // Indicates whether the loader should display the error state.
    private bool IsError { get; set; }

    // Cancels processing on the page side and lets LgLoaderView display the cancelled state.
    private Task CancelLoadingAsync()
    {
        IsLoading = false;
        return Task.CompletedTask;
    }

    // Reinitializes the page state before restarting processing.
    private Task RestartLoadingAsync()
    {
        IsError = false;
        IsLoading = true;
        return Task.CompletedTask;
    }
}

RGAA texts announced to screen readers

RgaaTextLoading and RgaaTextLoaded are passed to the screen reader announcement when the loading state changes. The default values are already translation keys.

AccessibleLoaderPage.razor

<LgLoaderView IsLoading="@IsLoading"
              RgaaTextLoading="#OrdersLoadingRgaa"
              RgaaTextLoaded="#OrdersLoadedRgaa">
    @("#OrdersReady".Translate())
</LgLoaderView>

AccessibleLoaderPage.razor.cs

public partial class AccessibleLoaderPage : LgPage
{
    // Loading state announced to assistive technologies by LgLoaderView.
    private bool IsLoading { get; set; }
}

Properties

Name	Type	Default	Declared in	Description
CancelDescription	string	null	LgLoaderView	Description displayed when the user cancels the action.
ChildContent	RenderFragment	null	LgLoaderView	Content rendered when loading is complete.
CssClass	string	null	LgLoaderView	Additional CSS classes applied to the loader container.
CustomTemplate	RenderFragment<Progress>	null	LgLoaderView	Custom rendering displayed during loading.
ErrorContent	RenderFragment	null	LgLoaderView	Content intended for the error state.
ErrorDescription	string	null	LgLoaderView	Description displayed in error state.
ErrorTitle	string	null	LgLoaderView	Title displayed in error state.
IsError	bool	false	LgLoaderView	Indicates whether the loader should display the error state.
IsLoading	bool	false	LgLoaderView	Indicates whether loading is in progress.
Label	string	null	LgLoaderView	Label displayed under the loading indicator.
OnActionCancellation	EventCallback	—	LgLoaderView	Cancellation callback; its presence displays a cancellation button.
OnActionRestart	EventCallback	—	LgLoaderView	Restart callback; its presence displays a restart button.
Progress	Progress	null	LgLoaderView	Progress instance tracked by the loader.
ProgressType	ProgressType	ProgressType.Circle	LgLoaderView	Rendering type used for determinate progress.
RgaaTextLoaded	string	#RgaaPageLoaded	LgLoaderView	Text announced when loading completes.
RgaaTextLoading	string	#RgaaPageLoading	LgLoaderView	Text announced when loading begins.

note

Progress Object

Lagoon.Helpers.Progress exposes in particular Message, Position, StartPosition, EndPosition, IsEnded, IsIndeterminate, and the events OnProgress, OnEnd, OnReset. LgLoaderView subscribes to these events to refresh its rendering.

Events

Name	Type	Description
OnActionCancellation	EventCallback	Triggered by the cancellation button displayed during loading.
OnActionRestart	EventCallback	Triggered by the restart button displayed after cancellation or error.

Associated enumerations

ProgressType

Rendering type for determinate progress. The default value is Circle.

Value	Description
Bar	Displays a LgProgress progress bar.
Circle	Displays circular progress LgCircleProgress (default value).

Accessibility

• LgLoaderView announces state changes via RgaaTextLoading and RgaaTextLoaded.
• In ProgressType.Bar mode, the progress rendered by LgProgress exposes role="progressbar", aria-valuenow, aria-valuemin, and aria-valuemax.
• Keep a translated Label to explain the current operation, especially in indeterminate loading.
• Final content remains in ChildContent, which avoids presenting incomplete data during loading.

Related components

• LgProgress — bar used by LgLoaderView in ProgressType.Bar mode.
• LgCircleProgress — circular progress used by default for determinate progress.
• LgBanner — persistent feedback after or during processing.