LgButton

LgButton is the Lagoon button component. It handles user actions (click, keyboard shortcut, command), navigation (URI / LgPageLink), form submission, tooltips, authorization policies, and several style and size variants.

<LgButton Text="My button" IconName="@IconNames.All.Check" />

• Namespace : Lagoon.UI.Components
• Inherits from : LgAriaComponentBase → LgComponentBase
• Interfaces : ILgComponentPolicies, IActionComponent, ILgFocusableComponent
• NuGet Package : Lagoon.UI

Specialized variants

LgButton serves as the base for several ready-to-use components: LgCopyButton (copy to clipboard) and LgPasteButton (paste from clipboard).

Usage

Demo

Try this component in the Lagoon showcase.

Simple button

Use Text to display the translated button label. If no size is specified, the cascading size is used, then ButtonSize.Medium.

OrderListPage.razor

<LgButton Text="#Refresh" OnClick="RefreshAsync" />

OrderListPage.razor.cs

public partial class OrderListPage : LgPage
{
    // Refreshes the displayed data: useful for restarting a search after an explicit user action.
    private async Task RefreshAsync(ActionEventArgs args)
    {
        await Task.Delay(100, args.CancellationToken);
        ShowSuccess("#OrderListRefreshed");
    }
}

Style, size, icon, and tooltip

Combine Kind, ButtonSize, IconName, and Tooltip to adjust the visual importance of the action. The keyboard shortcut, if present, is automatically added to the tooltip.

OrderActionsPage.razor

<LgButton Text="#ShowDetails"
          Kind="ButtonKind.Secondary"
          ButtonSize="ButtonSize.Small"
          IconName="@IconNames.All.InfoCircle"
          Tooltip="#ShowDetailsTooltip"
          TooltipPosition="TooltipPosition.Bottom"
          OnClick="ShowDetailsAsync" />

OrderActionsPage.razor.cs

public partial class OrderActionsPage : LgPage
{
    // Opens the details of the current item: secondary action, therefore styled as a subtle button.
    private Task ShowDetailsAsync(ActionEventArgs args)
    {
        ShowInformation("#OrderDetailsOpened");
        return Task.CompletedTask;
    }
}

Disabling and preventing double-click

Disabled immediately disables the button. PreventDoubleClick defaults to true: during the execution of an asynchronous action, the button is temporarily disabled to avoid concurrent processing.

OrderSavePage.razor

<LgButton Text="#Save"
          IconName="@IconNames.Save"
          Disabled="@IsLocked"
          PreventDoubleClick="true"
          OnClick="SaveAsync" />

OrderSavePage.razor.cs

public partial class OrderSavePage : LgPage
{
    // Indicates whether the screen is locked to prevent any modifications.
    private bool IsLocked { get; set; }

    // Persists changes: the button remains inactive while waiting to prevent duplicate saves.
    private async Task SaveAsync(ActionEventArgs args)
    {
        await Task.Delay(100, args.CancellationToken);
        ShowSuccess("#OrderSaved");
    }
}

Click handling

The OnClick event exposes ActionEventArgs. Use its CancellationToken to propagate cancellation to long-running operations triggered by the button.

OrderDeletePage.razor

<LgButton Text="#Delete"
          Kind="ButtonKind.Error"
          IconName="@IconNames.Delete"
          OnClick="DeleteAsync" />

OrderDeletePage.razor.cs

public partial class OrderDeletePage : LgPage
{
    // Deletes the current item: the token allows cleanly stopping processing if the action is canceled.
    private async Task DeleteAsync(ActionEventArgs args)
    {
        await Task.Delay(100, args.CancellationToken);
        ShowSuccess("#OrderDeleted");
    }
}

Navigation

Uri opens a raw route. Target allows opening the URI in another window. Link automatically inherits the title and icon from an LgPageLink if Text or IconName are not defined on the button.

OrderNavigationPage.razor

@* Internal navigation. *@
<LgButton Text="#OpenOrders" Uri="orders" />

@* Open in a new window. *@
<LgButton Text="#OpenHelp" Uri="help/orders" Target="_blank" />

@* Typed navigation to a Lagoon page. *@
<LgButton Link="@OrderEditPage.Link(CurrentOrderId)" />

OrderNavigationPage.razor.cs

public partial class OrderNavigationPage : LgPage
{
    // Identifier passed to the typed link to avoid manually rebuilding the URL.
    private int CurrentOrderId { get; set; } = 42;
}

Action priority

If Uri or Link provides a URI, the click navigates to that destination. Do not add OnClick to execute business logic in the same button: place that logic in the target page or use a button without a URI.

Form submission button

In an LgEditForm, IsSubmit="true" renders the button as type="submit" and triggers the parent form submission.

OrderEditPage.razor

<LgEditForm Model="Model" OnValidSubmit="OnValidSubmitAsync">
    <LgButton Text="#Save" IconName="@IconNames.Save" IsSubmit="true" />
</LgEditForm>

OrderEditPage.razor.cs

public partial class OrderEditPage : LgPage
{
    // Model edited by the form: it serves as the validation and save context.
    private OrderVm Model { get; } = new();

    // Triggered only when the form is valid: this is where to persist the model.
    private async Task OnValidSubmitAsync(EditContext editContext)
    {
        await Task.Delay(100);
        ShowSuccess("#OrderSaved");
    }

    private sealed class OrderVm
    {
        public string Reference { get; set; }
    }
}

warning

IsSubmit="true" is incompatible with ConfirmationMessage: the confirmation message must then be carried by the LgEditForm, not the button (an InvalidOperationException is thrown otherwise).

Confirmation message

ConfirmationMessage displays a confirmation request before executing the action or navigation. Do not use it with CommandName.

OrderDeleteConfirmPage.razor

<LgButton Text="#Delete"
          Kind="ButtonKind.Error"
          IconName="@IconNames.Delete"
          ConfirmationMessage="#ConfirmDeleteOrder"
          OnClick="DeleteAsync" />

OrderDeleteConfirmPage.razor.cs

public partial class OrderDeleteConfirmPage : LgPage
{
    // Executed only after confirmation: protects destructive actions from accidental clicks.
    private async Task DeleteAsync(ActionEventArgs args)
    {
        await Task.Delay(100, args.CancellationToken);
        ShowSuccess("#OrderDeleted");
    }
}

Keyboard shortcut

ShortcutKey associates a key with Ctrl. Prefix the key with @ to associate it with Alt instead.

OrderShortcutsPage.razor

@* Ctrl+S. *@
<LgButton Text="#Save" ShortcutKey="s" OnClick="SaveAsync" />

@* Alt+N. *@
<LgButton Text="#NewOrder" ShortcutKey="@@n" OnClick="CreateAsync" />

OrderShortcutsPage.razor.cs

public partial class OrderShortcutsPage : LgPage
{
    // Quick save: the shortcut avoids leaving the keyboard during input.
    private Task SaveAsync(ActionEventArgs args)
    {
        ShowSuccess("#OrderSaved");
        return Task.CompletedTask;
    }

    // Initializes a new record: useful for repetitive input screens.
    private Task CreateAsync(ActionEventArgs args)
    {
        ShowInformation("#OrderCreated");
        return Task.CompletedTask;
    }
}

DOM event behavior

PreventDefault cancels the default click behavior and StopPropagation prevents the click from bubbling to parent containers. This is useful in a row or panel that is itself clickable.

OrderRowPage.razor

<LgButton Text="#Select"
          PreventDefault="true"
          StopPropagation="true"
          OnClick="SelectAsync" />

OrderRowPage.razor.cs

public partial class OrderRowPage : LgPage
{
    // Selects only the button action, without triggering the parent container click.
    private Task SelectAsync(ActionEventArgs args)
    {
        ShowInformation("#OrderSelected");
        return Task.CompletedTask;
    }
}

Additional attributes, focus, and accessibility

Unrecognized attributes are passed to the rendered element. Use them for data-* attributes, and provide AriaLabel when a button is primarily identified by its icon. AutoFocus gives focus on first render.

OrderRefreshPage.razor

<LgButton Text="#Refresh"
          IconName="@IconNames.Load"
          AutoFocus="true"
          AriaLabel="#RefreshOrders"
          data-testid="refresh-orders"
          OnClick="RefreshAsync" />

OrderRefreshPage.razor.cs

public partial class OrderRefreshPage : LgPage
{
    // Restarts loading and receives focus on first display to facilitate keyboard usage.
    private Task RefreshAsync(ActionEventArgs args)
    {
        ShowSuccess("#OrderListRefreshed");
        return Task.CompletedTask;
    }
}

Commands bubbled to parent

CommandName and CommandArgument allow bubbling an action to a parent that listens for commands, for example an LgToolbar. The command must not be combined with ConfirmationMessage.

OrderToolbarPage.razor

<LgToolbar OnCommand="OnToolbarCommandAsync">
    <LgButton Text="#Archive"
              CommandName="archive"
              CommandArgument="@CurrentOrderId" />
    <LgButton Text="#Duplicate"
              CommandName="duplicate"
              CommandArgument="@CurrentOrderId" />
</LgToolbar>

OrderToolbarPage.razor.cs

public partial class OrderToolbarPage : LgPage
{
    // Identifier passed with the command so the parent knows which item to process.
    private int CurrentOrderId { get; set; } = 42;

    // Centralizes the toolbar actions: useful when multiple buttons share the same processing flow.
    private Task OnToolbarCommandAsync(CommandEventArgs args)
    {
        args.Handled = true;
        ShowInformation("#CommandReceived");
        return Task.CompletedTask;
    }
}

Visibility and activation by policy

PolicyVisible hides the button if the policy is not satisfied. PolicyEdit leaves it visible but non-editable if the user does not have permission to act.

AdminActionPage.razor

<LgButton Text="#Admin"
          PolicyVisible="@Policies.IsAdmin"
          PolicyEdit="@Policies.CanEdit"
          OnClick="OpenAdminAsync" />

AdminActionPage.razor.cs

public partial class AdminActionPage : LgPage
{
    // Opens the administration action only for users authorized by policies.
    private Task OpenAdminAsync(ActionEventArgs args)
    {
        ShowInformation("#AdminOpened");
        return Task.CompletedTask;
    }
}

Properties

All [Parameter] properties of the component, including inherited ones.

Name	Type	Default	Declared in	Description
AdditionalAttributes	IReadOnlyDictionary<string, object>	null	LgButton	Additional HTML attributes applied to the rendered element (captures unmapped values).
AutoFocus	bool	false	LgButton	Gives focus to the button on first render.
ButtonSize	ButtonSize?	null	LgButton	Button size. If not defined, the cascading value is used, otherwise the default size.
ChildContent	RenderFragment	null	LgButton	Custom button content.
CommandArgument	object	null	LgButton	Argument associated with the command sent to the handler. Use primitive types or string to optimize rendering.
CommandName	string	null	LgButton	Name of the command sent to the parent command handler (ICommandListener).
ConfirmationMessage	string	null	LgButton	Confirmation message displayed before the action. Incompatible with CommandName and IsSubmit.
CssClass	string	null	LgButton	Additional CSS classes.
Disabled	bool	false	LgButton	Disables the button.
IconName	string	null	LgButton	Displayed icon. Used via IconName="@IconNames.All.MyIcon".
IsSubmit	bool	false	LgButton	If true, the button is of type submit and triggers the parent LgEditForm.
Kind	ButtonKind	ButtonKind.Primary	LgButton	Style / variant of the button.
Link	LgPageLink	null	LgButton	Link information to a page. The Text and IconName from the link are used if not defined.
OnClick	EventCallback<ActionEventArgs>	—	LgButton	Callback triggered on button click.
PolicyEdit	string	null	LgButton	Policy required to enable (edit) the button.
PolicyVisible	string	null	LgButton	Policy required to display the button.
PreventDefault	bool	false	LgButton	Cancels the default behavior of the click event (@onclick:preventDefault).
PreventDoubleClick	bool	true	LgButton	Disables the button during action execution to prevent double-click.
ShortcutKey	string	null	LgButton	Character of the keyboard shortcut. Associated with Ctrl, or with Alt if prefixed by @.
StopPropagation	bool	true	LgButton	Stops the propagation of the click event (@onclick:stopPropagation).
Target	string	null	LgButton	Name of the browser window in which to open the Uri.
Text	string	null	LgButton	Button label.
Tooltip	string	null	LgButton	Tooltip.
TooltipIsHtml	bool	false	LgButton	Indicates whether the Tooltip content is in HTML format (otherwise plain text).
TooltipPosition	TooltipPosition	TooltipPosition.None	LgButton	Tooltip position.
Uri	string	null	LgButton	URI / route to open on click.
AriaLabel	string	null	LgAriaComponentBase	Value of the aria-label attribute.
AriaLabelledBy	string	null	LgAriaComponentBase	Value of the aria-labelledby attribute.

Cascading parameters

LgButton also consumes parameters automatically provided by ancestor components (you do not have to define them): ParentAuthorizeView (LgAuthorizeView), EditForm (parent LgEditForm, used by IsSubmit), and ButtonSizeCascading (ButtonSize?, default size inherited from an ancestor).

Events

Event	Type	Description
OnClick	EventCallback<ActionEventArgs>	Triggered on click (or keyboard shortcut). ActionEventArgs allows canceling or tracking action execution.

Associated enumerations

ButtonKind

Visual style of the button (Bootstrap variants).

Value	Description
Primary	Primary style (default value).
Secondary	Secondary style.
Success	Success style.
Error	Error style (danger).
Warning	Warning style.
Info	Info style.
Link	Link appearance.
Ghost	Ghost style (transparent background).
Custom	Custom style (no variant class imposed).

ButtonSize

Value	Description
Medium	Standard size (default value).
Small	Small size.
Large	Large size.

TooltipPosition

Value	Description
None	Undefined position (default value).
Top	Above.
Right	To the right.
Bottom	Below.
Left	To the left.

Accessibility

• Provide AriaLabel (or AriaLabelledBy) when the button displays only an icon to provide an accessible label.
• The keyboard shortcut configured via ShortcutKey is automatically added to the tooltip.

Related components

• LgCopyButton — copy to clipboard button.
• LgPasteButton — paste from clipboard button.
• LgLabelAction — label associated with an action button.