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.

csharp 
var calendar = new Calendar(2025, 11);
  
AnsiConsole.Write(calendar);

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

csharp 
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.

csharp 
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.

csharp 
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.

csharp 
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.

csharp 
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.

csharp 
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.

csharp 
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.

csharp 
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.

csharp 
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.

csharp 
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);

See Also

API Reference

A renderable calendar.

Constructors

public Calendar(DateTime date)

Initializes a new instance of the Calendar class.

Parameters:

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

Initializes a new instance of the Calendar class.

Parameters:

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

Initializes a new instance of the Calendar class.

Parameters:

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

Properties

Border : TableBorder

Gets or sets the border.

CalendarEvents : IList<CalendarEvent>

Gets a list containing all calendar events.

Culture : CultureInfo

Gets or sets the calendar's CultureInfo.

Day : int

Gets or sets the calendar day.

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

Gets or sets a value indicating whether or not to use a "safe" border on legacy consoles that might not be able to render non-ASCII characters.

Year : int

Gets or sets the calendar year.