LgDateBox

LgDateBox<TValue> enables input or selection of a day through a text field combined with a calendar (datepicker). It is the foundation of the date field family: LgMonthBox (month), LgWeekBox (week), and for similar functionality, LgYearBox (year).

<LgDateBox Label="#OrderDate" @bind-Value="_model.OrderDate" />

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

The bound type TValue must be DateOnly, DateTime, or DateTimeOffset (or their nullable versions). The field's suffix is reserved: the component automatically places the calendar icon there (Suffix / SuffixType are overwritten at initialization).

Usage

Demo

Try this component in the Lagoon showcase.

Simple input

Binding is done with @bind-Value. The default display format is the short date format of the current culture.

OrderEditPage.razor
<LgDateBox Label="#OrderDate" @bind-Value="_model.OrderDate" />

OrderEditPage.razor.cs
public partial class OrderEditPage : LgPage
{
    // Model being edited: the date is nullable to allow an empty field.
    private readonly OrderVm _model = new();

    private sealed class OrderVm
    {
        public DateTime? OrderDate { get; set; }
    }
}

Selection bounds

Min and Max disable dates outside the bounds in the calendar and invalidate the corresponding keyboard input.

BookingPage.razor
<LgDateBox Label="#BookingDate"
           Min="_minDate"
           Max="_maxDate"
           @bind-Value="_model.BookingDate" />

BookingPage.razor.cs
public partial class BookingPage : LgPage
{
    // Booking window allowed: bounds the calendar and keyboard input.
    private readonly DateTime _minDate = new(2026, 1, 1);
    private readonly DateTime _maxDate = new(2026, 12, 31);

    private readonly BookingVm _model = new();

    private sealed class BookingVm
    {
        public DateOnly? BookingDate { get; set; }
    }
}

Display format and keyboard input

DisplayFormat replaces the short date format of the current culture. KeyboardDisabled forces input through the calendar (the field becomes readonly for keyboard input). AssumeNearbyYear controls the expansion of two-digit years: the input "12/05/28" becomes 2028 as long as the year remains within AssumeNearbyYear years in the future (20 by default; a value less than 1 disables this behavior).

ContractPage.razor
<LgDateBox Label="#SignatureDate"
           DisplayFormat="dd/MM/yyyy"
           AssumeNearbyYear="30"
           @bind-Value="_model.SignatureDate" />

@* Selection only with the mouse, in the calendar. *@
<LgDateBox Label="#EffectiveDate"
           KeyboardDisabled="true"
           @bind-Value="_model.EffectiveDate" />

ContractPage.razor.cs
public partial class ContractPage : LgPage
{
    private readonly ContractVm _model = new();

    private sealed class ContractVm
    {
        public DateTime? SignatureDate { get; set; }
        public DateTime? EffectiveDate { get; set; }
    }
}

Time part of new values

When the bound value is an empty DateTime or DateTimeOffset, the new value created at selection uses DefaultTime (midnight by default), DefaultDateTimeKind (Unspecified by default), and for DateTimeOffset, DefaultTimeOffset (local time zone offset by default). If the bound value already contains a date, only the date part is replaced: the existing time is preserved.

MeetingPage.razor
<LgDateBox Label="#MeetingDate"
           DefaultTime="_defaultTime"
           DefaultDateTimeKind="DateTimeKind.Local"
           @bind-Value="_model.MeetingDate" />

MeetingPage.razor.cs
public partial class MeetingPage : LgPage
{
    // Time assigned to new dates: avoids creating meetings at midnight.
    private readonly TimeOnly _defaultTime = new(9, 0);

    private readonly MeetingVm _model = new();

    private sealed class MeetingVm
    {
        public DateTime? MeetingDate { get; set; }
    }
}

Responding to value changes

OnChangingAsync is called before assignment and allows canceling the change (args.Cancel). OnChange is called after. OnFocus notifies the focus event (this is also when the calendar loads).

PeriodPage.razor
<LgDateBox Label="#StartDate"
           OnChangingAsync="OnStartDateChangingAsync"
           OnChange="OnStartDateChanged"
           @bind-Value="_model.StartDate" />

PeriodPage.razor.cs
public partial class PeriodPage : LgPage
{
    private readonly PeriodVm _model = new();

    // Called before the change: set args.Cancel to reject the new date
    // (e.g., consistency with an already-entered end date).
    private Task OnStartDateChangingAsync(ChangingEventArgs<DateTime?> args)
    {
        if (args.NewValue > _model.EndDate)
        {
            args.Cancel = true;
            ShowWarning("#StartAfterEnd");
        }
        return Task.CompletedTask;
    }

    // Called after the change: useful for recalculating dependent data.
    private void OnStartDateChanged(ChangeEventArgs args)
    {
        ShowInformation("#PeriodUpdated");
    }

    private sealed class PeriodVm
    {
        public DateTime? StartDate { get; set; }
        public DateTime? EndDate { get; set; }
    }
}

Required field and reset button

Required forces the field to be mandatory (otherwise it is inferred from the [Required] attribute of the bound property). ResetButton displays a reset button; its default value comes from the application's behavior configuration.

DeadlinePage.razor
<LgEditForm Model="_model" OnValidSubmit="OnValidSubmitAsync">
    <LgDateBox Label="#Deadline"
               Required="true"
               ResetButton="true"
               @bind-Value="_model.Deadline" />
    <LgButton Text="#Save" IsSubmit="true" />
</LgEditForm>

DeadlinePage.razor.cs
public partial class DeadlinePage : LgPage
{
    private readonly DeadlineVm _model = new();

    // Triggered only when the form is valid: the date is guaranteed to be filled.
    private async Task OnValidSubmitAsync(EditContext editContext)
    {
        await Task.Delay(100);
        ShowSuccess("#DeadlineSaved");
    }

    private sealed class DeadlineVm
    {
        public DateTime? Deadline { get; set; }
    }
}

First day of the week

WeekStart changes the first day displayed in the calendar (Monday by default).

PlanningPage.razor
<LgDateBox Label="#PlanningDate"
           WeekStart="DayOfWeek.Sunday"
           @bind-Value="_model.PlanningDate" />

PlanningPage.razor.cs
public partial class PlanningPage : LgPage
{
    private readonly PlanningVm _model = new();

    private sealed class PlanningVm
    {
        public DateOnly? PlanningDate { get; set; }
    }
}

Properties

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

Name	Type	Default	Declared in	Description
`AssumeNearbyYear`	`int`	`20`	`LgDateBox`	Number of years in the future for which a two-digit year entered is attached to the current century. A value less than 1 disables this behavior.
`DefaultDateTimeKind`	`DateTimeKind`	`Unspecified`	`LgDateBox`	`DateTimeKind` used to create a new `DateTime`.
`DefaultTime`	`TimeOnly?`	`null`	`LgDateBox`	Time used to create a new `DateTime` or `DateTimeOffset` (midnight if `null`).
`DefaultTimeOffset`	`TimeSpan?`	`null`	`LgDateBox`	Time offset used to create a new `DateTimeOffset` (local time zone offset if `null`).
`DisplayFormat`	`string`	`null`	`LgDateBox`	Date display format (short date format of the current culture if `null`).
`KeyboardDisabled`	`bool`	`false`	`LgDateBox`	Prevents keyboard editing: the value can only be selected from the calendar.
`Max`	`DateTime?`	`null`	`LgDateBox`	Latest selectable date; later dates are disabled.
`Min`	`DateTime?`	`null`	`LgDateBox`	Earliest selectable date; earlier dates are disabled.
`OnChangeDisabled`	`bool`	`false`	`LgDateBox`	Disables the DOM `onchange` event in favor of `oninput` (used to avoid errors when the control is removed from rendering).
`OnChangingAsync`	`Func<ChangingEventArgs<TValue>, Task>`	`null`	`LgDateBox`	Callback invoked before value change; the change can be canceled there.
`OnFocus`	`EventCallback<FocusEventArgs>`	—	`LgDateBox`	Callback invoked on field focus.
`Placeholder`	`string`	`null`	`LgDateBox`	Hint text displayed when the field is empty.
`WeekStart`	`DayOfWeek`	`Monday`	`LgDateBox`	First day of the week in the calendar.
`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`	Focuses 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`	Field name used in input validation 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 for the label area.
`OnChange`	`EventCallback<ChangeEventArgs>`	—	`LgInputBase`	Callback invoked after value change.
`OnReset`	`EventCallback<ChangeEventArgs>`	—	`LgInputBase`	Callback invoked when the field is reset by the reset 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 reset button. If `null`, the application's behavior configuration applies.
`ResetText`	`string`	`null`	`LgInputBase`	Reset button text.
`ResetTextAriaLabel`	`string`	`null`	`LgInputBase`	Accessible label (`aria-label`) of the reset button.
`Tooltip`	`string`	`null`	`LgInputBase`	Tooltip.
`TooltipIsHtml`	`bool`	`false`	`LgInputBase`	Indicates whether the `Tooltip` content is in HTML format (otherwise plain text).
`Value`	`TValue`	—	`LgInputBase`	Bound value (`@bind-Value`).
`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

LgDateBox also consumes parameters automatically provided by ancestor components (you do not need to define them): ParentAuthorizeView (LgAuthorizeView) and the edit context of a parent LgEditForm.

Events

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

Associated enumerations

`InputLabelType`

Nature of the content of Prefix / Suffix.

Value	Description
`IconName`	Name of an icon from the library.
`Text`	Plain text (default value).

Best practices / accessibility

Prefer DateOnly? when only the date matters: this avoids surprises from time and time zone parts specific to DateTime / DateTimeOffset.
Do not set Suffix / SuffixType: they are overwritten by the calendar icon at component initialization.
For a "month," "week," or "year" field, use the specialized component instead of LgDateBox with a custom format.

Complete reference

All parameters (including inherited ones): API Reference — LgDateBox.

LgMonthBox — month selection.
LgWeekBox — week selection.
LgYearBox — year selection.
LgTimeBox — time input.
LgGridDateColumn — date column of a LgGridView.

Usage​

Demo​

Simple input​

Selection bounds​

Display format and keyboard input​

Time part of new values​

Responding to value changes​

Required field and reset button​

First day of the week​

Properties​

Events​

Associated enumerations​

InputLabelType​

Best practices / accessibility​

Related components​