CalendarView

CalendarView is a SwiftUI wrapper of UICalendarView, which is a view that displays a calendar that provides for user selection of a single date or multiple dates. It also allows for displaying date-specific decorations.

More info on its full capabilities can be found at Apple's documentation for UICalendarView.

The minimum needed to work with CalendarView is to attach it to a Binding variable with a DateComponents type. If you want to limit date selection to a single date at a time, use an optional DateComponents. To allow multiple date selection, the Binding should be a Set<DateComponents> (a Set of DateComponents).

struct ContentView: View {
    @State
    private var singleDateSelection: DateComponents? = nil

    @State
    private var multipleDateSelection: Set<DateComponents> = []

    var body: some View {
        VStack {
            // No selection tracking
            CalendarView()

            // Single date selection tracking
            CalendarView($singleDateSelection)

            // Multiple date selection tracking
            CalendarView($multipleDateSelection)
        }
    }
}

Some elements of the CalendarView can be set with SwiftUI Environment and its standard ViewModifier (environment(_:_:)).

This also means that CalendarView also reacts to these settings if they're set in the parent Environment. And for convenience, the package comes with abbreviated modifiers to directly set these values.

These elements are:

• The actual calendar system (calendar/Calendar)
  • i.e. Gregorian vs. Chinese vs. Buddhist
• The language (locale/Locale)
• The time zone (timeZone/TimeZone)
  • Changing this won't have a visual effect, but the selected DateComponent values it outputs will have the applied TimeZone (or the one in the active Environment) pre-set.

CalendarView($selectedDate)
    // Environment Modifier
    // Calendar
    .environment(\.calendar, Calendar(identifier: .chinese))
    // Locale
    .environment(\.locale, Locale(identifier: "en_GB"))
    // Time Zone
    .environment(\.timeZone, TimeZone(identifier: "America/Chicago")!)

    // Convenience Modifiers
    // Calendar
    .calendar(Calendar(identifier: .chinese))
    // Locale
    .locale(Locale(identifier: "en_GB"))
    // Time Zone
    .timeZone(TimeZone(identifier: "America/Chicago")!)

Another feature of UICalendarView (and therefore, CalendarView by proxy), is to display "decorations" along with any of the dates in the calendar. These can be different for different dates in the calendar, one type of decoration for all dates, or no decorations whatsoever.

The different types of decorations are as follows:

• default(color: Color? = nil, size: DecorationSize = .medium)
  • A decoration with a filled circle image, using the color and size you specify.
• image(_ systemName: String, color: Color? = nil, size: DecorationSize = .medium)
  • A decoration with the image, color, and size that you specify.
  • You can specify an image with a UIImage or the name of an SF Symbols icon.
  • If you don't specify an image, it defaults to the circlebadge.fill symbol.
  • If you don't specify a color, it defaults to systemFill.
• custom(@ViewBuilder _ customViewProvider: () -> some View)
  • A custom decoration with a custom SwiftUI view, via a @ViewBuilder closure.

CalendarView($selectedDate)
    // This sets an orange `star.fill` symbol under all dates in the calendar.
    .decorations(.image("star.fill", color: .orange))
    // This displays the month number under each date (why not?) using a SwiftUI ViewBuilder
    .decorations { dateComponents in
        Text(dateComponents.month ?? 0, format: .number)
    }

The font design that the calendar view uses for displaying calendar text. CalendarView comes with a ViewModifier to set this:

CalendarView($selectedDate)
    .fontDesign(.rounded)

Using the visibleDateComponents parameter in CalendarView's initializer (Binding<DateComponents?>), you can control the visible part of in the calendar view. It can also be used to keep track of what part of the calendar is currently be used.

struct ContentView: View {
    @State
    private var selectedDate: DateComponents? = nil

    // This sets the initial month shown to May 2024
    @State
    private var currentlyViewedComponents: DateComponents? = .init(
        calendar: calendar,
        year: 2024,
        month: 5
    )

    var body: some View {
        CalendarView(
            $selectedDate,
            visibleDateComponents: $currentlyViewedComponents
        )
    }
}

Using the availableDateRange parameter in CalendarView's initializer (DateInterval), you can control the range of dates that the calendar view is able to display. Setting this parameter restricts the earliest or latest dates that the calendar view displays. The default date range is from distantPast to distantFuture.

For convenience, an extra protocol comes with the package: DateRangeExpression, which allows a DateInterval to be initialized from a few of the range types. Additionally, it comes with support for using "Range-literal" syntax with Date values to create a DateInterval value. Specifically, it works with the syntax for:

• ClosedRange: date1...date2
• PartialRangeFrom: date1...
  • Open upper end of range is set to distantFuture.
• PartialRangeThrough: ...date2
  • Open lower end of range is set to distantPast.

CalendarView(
    $selectedDate,
    // This would only allow the user to select
    // a date from the current moment in time onward.
    availableDateRange: Date.now...
)