LgYearBox

LgYearBox<TValue> allows you to enter or select a year via a text field combined with a year selector. Unlike the rest of the date family (LgDateBox), the bound value is an integer (int or int?): the year itself.

<LgYearBox Label="#FiscalYear" @bind-Value="_model.FiscalYear" />

• Namespace: Lagoon.UI.Components
• Inherits from: LgInputRenderBase<TValue> → LgInputBase<TValue> → LgAriaComponentBase → LgComponentBase
• NuGet package: Lagoon.UI

The field suffix is reserved: the component automatically places the calendar icon there (Suffix / SuffixType are overwritten on initialization).

Usage

Demo

Try this component in the Lagoon showcase.

Simple input

BudgetPage.razor

<LgYearBox Label="#FiscalYear" @bind-Value="_model.FiscalYear" />

BudgetPage.razor.cs

public partial class BudgetPage : LgPage
{
    // Model being edited: the year is nullable to allow an empty field.
    private readonly BudgetVm _model = new();

    private sealed class BudgetVm
    {
        public int? FiscalYear { get; set; }
    }
}

Selection bounds

Min and Max (integers) disable years outside the bounds in the selector.

ArchivePage.razor

<LgYearBox Label="#ArchiveYear"
           Min="2000"
           Max="2026"
           @bind-Value="_model.ArchiveYear" />

ArchivePage.razor.cs

public partial class ArchivePage : LgPage
{
    private readonly ArchiveVm _model = new();

    private sealed class ArchiveVm
    {
        public int? ArchiveYear { get; set; }
    }
}

Reacting to value changes

OnChangingAsync is called before the assignment and allows you to cancel the change (args.Cancel); OnChange (inherited) is called after.

CampaignPage.razor

<LgYearBox Label="#CampaignYear"
           OnChangingAsync="OnYearChangingAsync"
           @bind-Value="_model.CampaignYear" />

CampaignPage.razor.cs

public partial class CampaignPage : LgPage
{
    private readonly CampaignVm _model = new();

    // Called before the change: refuses years with no known campaign.
    private Task OnYearChangingAsync(ChangingEventArgs<int?> args)
    {
        if (args.NewValue < 2010)
        {
            args.Cancel = true;
            ShowWarning("#NoCampaignBefore2010");
        }
        return Task.CompletedTask;
    }

    private sealed class CampaignVm
    {
        public int? CampaignYear { get; set; }
    }
}

Properties

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

Name	Type	Default	Declared in	Description
Max	int?	null	LgYearBox	Latest selectable year; later years are disabled.
Min	int?	null	LgYearBox	Earliest selectable year; earlier years are disabled.
OnChangingAsync	Func<ChangingEventArgs<TValue>, Task>	null	LgYearBox	Callback called before the value changes; the change can be canceled there.
OnFocus	EventCallback<FocusEventArgs>	—	LgYearBox	Callback called when focus is taken.
Placeholder	string	null	LgYearBox	Indicator text displayed when the field is empty.
Prefix	string	null	LgInputRenderBase	Prefix displayed in the field.
PrefixType	InputLabelType	Text	LgInputRenderBase	Nature of the prefix.
Suffix	string	(calendar icon)	LgInputRenderBase	Suffix displayed in the field. Reserved: the component places the calendar icon there.
SuffixType	InputLabelType	IconName	LgInputRenderBase	Nature of the suffix. Reserved by the component.
AdditionalAttributes	IReadOnlyDictionary<string, object>	null	LgInputBase	Additional HTML attributes applied to the rendered element.
AutoFocus	bool	false	LgInputBase	Gives focus to the field on first render.
ConfirmationMessage	string	null	LgInputBase	Confirmation message displayed before applying a value change.
Container	IInputContainer<TValue>	null	LgInputBase	Internal use: attaches a GridView cell to the field.
CssClass	string	null	LgInputBase	Additional CSS classes.
Disabled	bool	false	LgInputBase	Disables the field.
DisplayName	string	null	LgInputBase	Name of the field used in input error messages.
HideValidationMessage	bool	false	LgInputBase	Hides the validation message below the field.
Label	string	null	LgInputBase	Field label.
LabelContent	RenderFragment	null	LgInputBase	Custom content of the label area.
OnChange	EventCallback<ChangeEventArgs>	—	LgInputBase	Callback called after the value changes.
OnReset	EventCallback<ChangeEventArgs>	—	LgInputBase	Callback called when the field is reset by the clear button.
PolicyEdit	string	null	LgInputBase	Policy required to edit the field.
PolicyVisible	string	null	LgInputBase	Policy required to display the field.
ReadOnly	bool	false	LgInputBase	Displays the field as read-only.
Required	bool?	null	LgInputBase	Required field. If null, inferred from the [Required] attribute of the bound property.
ResetButton	bool?	null	LgInputBase	Displays the clear button. If null, the application's behavior configuration applies.
ResetText	string	null	LgInputBase	Clear button text.
ResetTextAriaLabel	string	null	LgInputBase	Accessible label (aria-label) of the clear button.
Tooltip	string	null	LgInputBase	Help tooltip.
TooltipIsHtml	bool	false	LgInputBase	Indicates whether the Tooltip content is in HTML format (otherwise plain text).
Value	TValue	—	LgInputBase	Bound value (@bind-Value), of type int or int?.
ValueChanged	EventCallback<TValue>	—	LgInputBase	Callback for updating the bound value.
ValueExpression	Expression<Func<TValue>>	—	LgInputBase	Expression identifying the bound property.
AriaLabel	string	null	LgAriaComponentBase	Value of the aria-label attribute.
AriaLabelledBy	string	null	LgAriaComponentBase	Value of the aria-labelledby attribute.

Cascading parameters

LgYearBox also consumes parameters automatically provided by ancestor components (you don't need to define them): ParentAuthorizeView (LgAuthorizeView) and the edit context of a parent LgEditForm.

Events

Event	Type	Description
OnChangingAsync	Func<ChangingEventArgs<TValue>, Task>	Before the value changes; args.Cancel = true cancels the change.
OnChange	EventCallback<ChangeEventArgs>	After the value changes.
OnFocus	EventCallback<FocusEventArgs>	When the field takes focus.
OnReset	EventCallback<ChangeEventArgs>	When reset by the clear button.

Best practices / accessibility

• The bound value must be int or int?: any other type causes a runtime error.
• Do not set Suffix / SuffixType: they are overwritten by the calendar icon on component initialization.

Complete reference

All parameters (including inherited): API Reference — LgYearBox.

Related components

• LgDateBox — day selection.
• LgMonthBox — month selection.
• LgWeekBox — week selection.
• LgGridYearColumn — year column of an LgGridView.