Spectre.Console

Calendar Widget

Display monthly calendars with highlighted dates and events

The Calendar widget renders monthly calendars with customizable date highlighting and event tracking.

Screenshot

When to Use

Use Calendar when you need to visualize dates and events in a month view. Common scenarios:

  • Scheduling and planning: Display project timelines, deadlines, or milestone dates
  • Event tracking: Highlight important dates like releases, meetings, or reminders
  • Date selection interfaces: Show available or unavailable dates in CLI tools
  • Multi-month comparisons: Display several months side by side to show patterns

For displaying dates inline within text, use Markup with formatted date strings. For progress over time, use BarChart to show metrics across time periods.

Basic Usage

Create a calendar by specifying the year and month. Events are marked with an asterisk and highlighted in blue by default.

public static void BasicCalendarExample()
{
    var calendar = new Calendar(2025, 11);
  
    AnsiConsole.Write(calendar);
}

You can also create a calendar from a DateTime object to show the current month.

public static void CalendarFromDateExample()
{
    var today = DateTime.Now;
    var calendar = new Calendar(today);
  
    AnsiConsole.Write(calendar);
}

Highlighting Dates

Adding Calendar Events

Use AddCalendarEvent() to mark specific dates as important. Each event appears with an asterisk indicator.

public static void CalendarEventsExample()
{
    var calendar = new Calendar(2025, 11)
        .AddCalendarEvent(2025, 11, 15)
        .AddCalendarEvent(2025, 11, 20)
        .AddCalendarEvent(2025, 11, 28);
  
    AnsiConsole.Write(calendar);
}

You can pass DateTime objects instead of individual year, month, and day values.

public static void CalendarEventDateTimeExample()
{
    var calendar = new Calendar(2025, 11)
        .AddCalendarEvent(new DateTime(2025, 11, 7))
        .AddCalendarEvent(new DateTime(2025, 11, 14))
        .AddCalendarEvent(new DateTime(2025, 11, 21));
  
    AnsiConsole.Write(calendar);
}

Customizing Event Styles

Use HighlightStyle() to change the default appearance for all event dates.

public static void CalendarHighlightStyleExample()
{
    var calendar = new Calendar(2025, 11)
        .HighlightStyle(new Style(foreground: Color.Red, decoration: Decoration.Bold))
        .AddCalendarEvent(2025, 11, 1)
        .AddCalendarEvent(2025, 11, 15)
        .AddCalendarEvent(2025, 11, 25);
  
    AnsiConsole.Write(calendar);
}

For more control, assign custom styles to individual events by passing a Style to AddCalendarEvent(). This is useful when different events have different priorities or categories.

public static void CalendarCustomEventStylesExample()
{
    var calendar = new Calendar(2025, 11)
        .AddCalendarEvent(2025, 11, 5, new Style(Color.Green))
        .AddCalendarEvent(2025, 11, 15, new Style(Color.Yellow))
        .AddCalendarEvent(2025, 11, 25, new Style(Color.Red));
  
    AnsiConsole.Write(calendar);
}

Customizing Appearance

Header Styling

Use HeaderStyle() to customize the month and year display at the top of the calendar.

public static void CalendarHeaderStyleExample()
{
    var calendar = new Calendar(2025, 11)
        .HeaderStyle(new Style(foreground: Color.Blue, decoration: Decoration.Bold))
        .AddCalendarEvent(2025, 11, 10);
  
    AnsiConsole.Write(calendar);
}

Use HideHeader() when you need a more compact display or when the month is obvious from context.

public static void CalendarHideHeaderExample()
{
    var calendar = new Calendar(2025, 11)
        .HideHeader()
        .AddCalendarEvent(2025, 11, 15);
  
    AnsiConsole.Write(calendar);
}

Border Styles

Customize the calendar border to match your application's visual style. Since Calendar uses a table internally, all table borders are supported.

public static void CalendarBorderExample()
{
    AnsiConsole.MarkupLine("[yellow]Rounded border:[/]");
    var rounded = new Calendar(2025, 11)
        .Border(TableBorder.Rounded)
        .AddCalendarEvent(2025, 11, 10);
    AnsiConsole.Write(rounded);
  
    AnsiConsole.WriteLine();
    AnsiConsole.MarkupLine("[yellow]Double border:[/]");
    var double_ = new Calendar(2025, 11)
        .Border(TableBorder.Double)
        .AddCalendarEvent(2025, 11, 10);
    AnsiConsole.Write(double_);
}

Note

See the Table Border Reference for all available border styles.

Localization

Culture Support

Set the Culture property to control the week start day, day names, and month formatting. This ensures calendars match your users' regional expectations.

public static void CalendarCultureExample()
{
    AnsiConsole.MarkupLine("[yellow]US culture (Sunday start):[/]");
    var usCulture = new Calendar(2025, 11)
    {
        Culture = new CultureInfo("en-US")
    };
    usCulture.AddCalendarEvent(2025, 11, 15);
    AnsiConsole.Write(usCulture);
  
    AnsiConsole.WriteLine();
    AnsiConsole.MarkupLine("[yellow]French culture (Monday start):[/]");
    var frenchCulture = new Calendar(2025, 11)
    {
        Culture = new CultureInfo("fr-FR")
    };
    frenchCulture.AddCalendarEvent(2025, 11, 15);
    AnsiConsole.Write(frenchCulture);
}

Advanced Usage

Multiple Calendars

Display several months together using the Columns widget. This is useful for showing quarterly views or comparing date ranges.

public static void MultipleCalendarsExample()
{
    var november = new Calendar(2025, 11)
        .AddCalendarEvent(2025, 11, 15);
  
    var december = new Calendar(2025, 12)
        .AddCalendarEvent(2025, 12, 25);
  
    var january = new Calendar(2026, 1)
        .AddCalendarEvent(2026, 1, 1);
  
    var columns = new Columns(november, december, january);
    AnsiConsole.Write(columns);
}

API Reference

A renderable calendar.

Constructors

Calendar(DateTime date)

Initializes a new instance of the class.

Parameters:

date (DateTime)
The calendar date.
Calendar(int year, int month)

Initializes a new instance of the class.

Parameters:

year (int)
The calendar year.
month (int)
The calendar month.
Calendar(int year, int month, int day)

Initializes a new instance of the class.

Parameters:

year (int)
The calendar year.
month (int)
The calendar month.
day (int)
The calendar day.

Properties

Alignment : Nullable<Justify>
Border : TableBorder
BorderStyle : Style
CalendarEvents : IList<CalendarEvent>

Gets a list containing all calendar events.

Culture : CultureInfo

Gets or sets the calendar's .

Day : int

Gets or sets the calendar day.

HeaderStyle : Style

Gets or sets the header style.

HighlightStyle : Style

Gets or sets the calendar's highlight .

Month : int

Gets or sets the calendar month.

ShowHeader : bool

Gets or sets a value indicating whether or not the calendar header should be shown.

UseSafeBorder : bool
Year : int

Gets or sets the calendar year.

Extension Methods

Calendar AddCalendarEvent(DateTime date, Style customEventHighlightStyle)

Adds a calendar event.

Parameters:

date (DateTime)
The calendar event date.
customEventHighlightStyle (Style)
The calendar event custom highlight style.

Returns:

The same instance so that multiple calls can be chained.

Calendar AddCalendarEvent(string description, DateTime date, Style customEventHighlightStyle)

Adds a calendar event.

Parameters:

description (string)
The calendar event description.
date (DateTime)
The calendar event date.
customEventHighlightStyle (Style)
The calendar event custom highlight style.

Returns:

The same instance so that multiple calls can be chained.

Calendar AddCalendarEvent(int year, int month, int day, Style customEventHighlightStyle)

Adds a calendar event.

Parameters:

year (int)
The year of the calendar event.
month (int)
The month of the calendar event.
day (int)
The day of the calendar event.
customEventHighlightStyle (Style)
The calendar event custom highlight style.

Returns:

The same instance so that multiple calls can be chained.

Calendar AddCalendarEvent(string description, int year, int month, int day, Style customEventHighlightStyle)

Adds a calendar event.

Parameters:

description (string)
The calendar event description.
year (int)
The year of the calendar event.
month (int)
The month of the calendar event.
day (int)
The day of the calendar event.
customEventHighlightStyle (Style)
The calendar event custom highlight style.

Returns:

The same instance so that multiple calls can be chained.

IEnumerable<Segment> GetSegments(IAnsiConsole console)

Gets the segments for a renderable using the specified console.

Parameters:

console (IAnsiConsole)
The console.

Returns:

An enumerable containing segments representing the specified .

Calendar HeaderStyle(Style style)

Sets the calendar's header .

Parameters:

style (Style)
The header style.

Returns:

The same instance so that multiple calls can be chained.

Calendar HideHeader()

Hides the calendar header.

Returns:

The same instance so that multiple calls can be chained.

Calendar HighlightStyle(Style style)

Sets the calendar's highlight .

Parameters:

style (Style)
The default highlight style.

Returns:

The same instance so that multiple calls can be chained.

Calendar ShowHeader()

Shows the calendar header.

Returns:

The same instance so that multiple calls can be chained.