LgCalendar

LgCalendar displays an annual calendar or a period spanning several months, with one row per day. Use it to visualize periods, absences, availabilities, or any business indicator distributed over dates.

<LgCalendar Indicators="@(Array.Empty<CalendarIndicator>())" />

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

Usage

Demo

Try this component in the Lagoon showcase.

Annual calendar without indicator

Provide an empty collection to Indicators when using the default rendering without colored ranges. StartDate and EndDate default to the first and last day of the current year.

AnnualCalendarPage.razor

<LgCalendar StartDate="StartDate"
            EndDate="EndDate"
            Indicators="CalendarIndicators"
            OnDayClick="SelectDayAsync" />

AnnualCalendarPage.razor.cs

public partial class AnnualCalendarPage : LgPage
{
    // Start date displayed by the annual calendar.
    private DateTime StartDate { get; set; } = new(DateTime.Today.Year, 1, 1);

    // End date displayed by the annual calendar.
    private DateTime EndDate { get; set; } = new(DateTime.Today.Year, 12, 31);

    // Empty collection required for standard rendering when no indicator is displayed.
    private IEnumerable<CalendarIndicator> CalendarIndicators { get; set; } = Array.Empty<CalendarIndicator>();

    // Handles a click on a day and reuses the date provided by the Lagoon event.
    private Task SelectDayAsync(ClickDayEventArgs args)
    {
        ShowInformation("#CalendarDaySelected");
        return Task.CompletedTask;
    }
}

Display colored periods

Indicators contains the indicator families. Each CalendarIndicator defines a tooltip label, a color or CSS class, and then a collection of period ranges CalendarIndicatorRangeCollection. An indicator occupies one column in each day and its periods are evaluated date by date.

LeaveCalendarPage.razor

<LgCalendar CssClass="leave-calendar"
            StartDate="StartDate"
            EndDate="EndDate"
            Indicators="LeaveIndicators"
            OnDayClick="OpenDayAsync" />

LeaveCalendarPage.razor.cs

public partial class LeaveCalendarPage : LgPage
{
    // Start boundary of the year tracked by the screen.
    private DateTime StartDate { get; set; } = new(2024, 1, 1);

    // End boundary of the year tracked by the screen.
    private DateTime EndDate { get; set; } = new(2024, 12, 31);

    // Business indicators displayed in the calendar cells.
    private List<CalendarIndicator> LeaveIndicators { get; set; } = new();

    // Prepares the colored periods before the page is displayed.
    protected override Task OnInitializedAsync()
    {
        CalendarIndicatorRangeCollection schoolRanges = new()
        {
            new CalendarIndicatorRange
            {
                StartDate = new DateTime(2024, 2, 12),
                EndDate = new DateTime(2024, 2, 23)
            },
            new CalendarIndicatorRange
            {
                StartDate = new DateTime(2024, 4, 15),
                EndDate = new DateTime(2024, 4, 26)
            }
        };

        CalendarIndicatorRangeCollection teamRanges = new()
        {
            new CalendarIndicatorRange
            {
                StartDate = new DateTime(2024, 7, 8),
                EndDate = new DateTime(2024, 7, 19)
            }
        };

        LeaveIndicators = new List<CalendarIndicator>
        {
            new CalendarIndicator
            {
                Id = "schoolHolidays",
                Label = "#SchoolHolidays",
                Color = "#e95420",
                Ranges = schoolRanges
            },
            new CalendarIndicator
            {
                Id = "teamLeave",
                Label = "#TeamLeave",
                CssClass = "team-leave-indicator",
                Ranges = teamRanges
            }
        };

        return base.OnInitializedAsync();
    }

    // Opens the business details associated with the selected day.
    private Task OpenDayAsync(ClickDayEventArgs args)
    {
        ShowInformation("#CalendarDayOpened");
        return Task.CompletedTask;
    }
}

Customize day rendering

DayContent completely replaces the internal rendering of each day. In this mode, the component passes the current date to the RenderFragment<DateTime> fragment and you choose the content to display.

PlanningCalendarPage.razor

<LgCalendar StartDate="StartDate" EndDate="EndDate">
    <DayContent Context="day">
        <LgLabel Text="@(GetDayLabel(day))" />
    </DayContent>
</LgCalendar>

PlanningCalendarPage.razor.cs

public partial class PlanningCalendarPage : LgPage
{
    // First day of the displayed period.
    private DateTime StartDate { get; set; } = new(DateTime.Today.Year, 1, 1);

    // Last day of the displayed period.
    private DateTime EndDate { get; set; } = new(DateTime.Today.Year, 12, 31);

    // Provides a different translation key for weekends.
    private static string GetDayLabel(DateTime day)
    {
        return day.DayOfWeek is DayOfWeek.Saturday or DayOfWeek.Sunday
            ? "#CalendarWeekendDay"
            : "#CalendarWorkingDay";
    }
}

Associated data types

CalendarIndicator describes a family of ranges displayed in the calendar.

Name	Type	Description
Id	string	Business identifier of the indicator.
Label	string	Label used in the tooltip of the range. Use a #... key.
Color	string	CSS color applied as the background color of the indicator.
CssClass	string	CSS class added to the indicator.
Ranges	CalendarIndicatorRangeCollection	Periods attached to this indicator.

CalendarIndicatorRangeCollection inherits from List<CalendarIndicatorRange>.

Name	Type	Description
StartDate	DateTime	First day included in the period.
EndDate	DateTime	Last day included in the period.

Properties

Name	Type	Default	Declared in	Description
Id	string	"cld" + Guid.NewGuid().ToString("N")	LgCalendar	HTML identifier of the calendar container.
CssClass	string	null	LgCalendar	CSS classes added to the calendar container.
StartDate	DateTime	new DateTime(DateTime.Now.Year, 1, 1)	LgCalendar	Start date of the displayed period.
EndDate	DateTime	new DateTime(DateTime.Now.Year, 12, 31)	LgCalendar	End date of the displayed period.
Indicators	IEnumerable<CalendarIndicator>	null	LgCalendar	Colored indicators displayed in the standard day rendering.
DayContent	RenderFragment<DateTime>	null	LgCalendar	Custom fragment receiving the date of the day to render.
OnDayClick	EventCallback<ClickDayEventArgs>	default	LgCalendar	Handler called when a day is clicked.

Events

Name	Type	Description
OnDayClick	EventCallback<ClickDayEventArgs>	Triggered when the user clicks on a day. ClickDayEventArgs.Date contains the selected date.

Accessibility

The generated container has aria-hidden="true": the calendar is therefore ignored by assistive technologies. Do not use it as the only means to convey critical information; add a text summary, a data grid, or accessible details nearby. Indicator labels are rendered as a title attribute and should use translation keys.

Related components

• LgLabel: displays summary content in a custom DayContent.
• LgGridView: presents the accessible list of periods or events represented in the calendar.