Theming#

Every visual decision a Kalendar view makes — colour, text style, corner shape, size, spacing, motion, and the words it speaks to a screen reader — resolves through an ambient set of design tokens. Nothing is hard-coded, and nothing reads your MaterialTheme at render time.

The rule to hold onto:

Kalendar reads Material only to derive default token values. No Material widget renders the calendar. An app with its own design system controls rendering completely, through tokens and slots.

Concretely: the only Material types the view package touches are MaterialTheme, ColorScheme, and Typography, and only inside KalendarThemeDefaults to read default colours and text styles. Every pixel is drawn with Compose Foundation — the text, the icons, the jump picker, the dividers. Replace the default token values and Material is out of the picture entirely.

That means a Material 3 app gets a calendar that matches its colour scheme for free, and a non-Material app can restyle every pixel without fighting a Material dependency it never wanted.

The shape of the API#

It mirrors MaterialTheme deliberately, so it should already feel familiar:

Wrapping is optional. A view used outside any KalendarTheme falls back to KalendarThemeDefaults, so reading a token is always safe.

Overriding one token#

Each token set is independent, so overriding one leaves the other five alone:

import com.himanshoe.kalendar.theme.KalendarTheme
import com.himanshoe.kalendar.theme.KalendarThemeDefaults

KalendarTheme(
    colors = KalendarThemeDefaults.colors().copy(selectionBackground = BrandPurple),
) {
    KalendarMonth(selectedDate = today)
}

KalendarColors, KalendarTypography, and KalendarShapes have no default constructor values — every field is required — so you must start from an existing instance and copy it. The other three are fully defaulted, so you can construct them directly:

KalendarTheme(dimensions = KalendarDimensions(hourHeight = 96.dp)) {
    KalendarSchedule(state = rememberKalendarScheduleState(initialDate = today))
}

Warning: constructing a token set directly resets every field you did not name back to the built-in default. Inside a nested KalendarTheme, that silently discards the outer theme's values. To layer on top of whatever is already ambient, copy the accessor instead:

kotlinCopy

KalendarTheme(dimensions = KalendarTheme.dimensions.copy(hourHeight = 96.dp)) {
    KalendarSchedule(state = rememberKalendarScheduleState(initialDate = today))
}

Note: the token classes are @Immutable classes with hand-written members, not data classes. copy(), equals(), hashCode(), and toString() all work exactly as you would expect — which matters, because value equality is what lets Compose skip recomposition when a theme is rebuilt with the same values. Destructuring (val (a, b) = tokens) is the one data-class convenience they do not have.

Reading tokens#

The KalendarTheme object exposes the ambient values, for building custom cells and slots that match the rest of the calendar:

@Composable
fun MyDayCell(scope: KalendarDayScope<*>) {
    val colors = KalendarTheme.colors
    val typography = KalendarTheme.typography

    Text(
        text = scope.date.day.toString(),
        color = if (scope.isToday) colors.todayContent else colors.dayContent,
        style = if (scope.isSelected) typography.dayNumberEmphasized else typography.dayNumber,
    )
}

All of them are @Composable getters, and all fall back to KalendarThemeDefaults outside a KalendarTheme.

Colours#

KalendarColors carries fourteen required colours, three derived ones, and four alpha values.

And the four alphas, which are the same in every palette:

Note: the calendar's container fill has two sources. KalendarColors.background is the token; KalendarViewConfig.background is a per-view Brush? that overrides it when non-null. Use the token for a colour, and the config only for something a colour cannot express — a gradient, say.

Apps that use Material 3#

Do nothing. KalendarThemeDefaults.colors() derives from the ambient MaterialTheme.colorScheme, so your brand colours and your light/dark scheme are already applied.

Apps without Material 3#

MaterialTheme.colorScheme falls back to Compose's baseline light scheme when no MaterialTheme is present — which means a calendar in a non-Material app would stay light even in dark mode. Pass one of Kalendar's own Material-free palettes instead:

KalendarTheme(colors = KalendarThemeDefaults.systemColors()) {
    KalendarMonth(selectedDate = today)
}

Use lightColors() / darkColors() when your app drives its own theme switch rather than following the system:

KalendarTheme(
    colors = if (myAppIsInDarkMode) {
        KalendarThemeDefaults.darkColors()
    } else {
        KalendarThemeDefaults.lightColors()
    },
) {
    KalendarMonth(selectedDate = today)
}

Or map your own design system onto the tokens directly, cutting the Material link entirely:

KalendarTheme(
    colors = KalendarColors(
        background = MyTheme.surface,
        selectionBackground = MyTheme.accentMuted,
        onSelectionBackground = MyTheme.onAccentMuted,
        todayContent = MyTheme.accent,
        dayContent = MyTheme.textPrimary,
        dayLabelContent = MyTheme.textSecondary,
        headerContent = MyTheme.textPrimary,
        eventIndicator = MyTheme.accent,
        nowIndicator = MyTheme.danger,
        gridLine = MyTheme.divider,
        dragGhostBackground = MyTheme.accentMuted,
        popupBackground = MyTheme.surfaceRaised,
        popupBorder = MyTheme.divider,
    ),
) {
    KalendarMonth(selectedDate = today)
}

Every colour is a required constructor parameter, so the compiler tells you when a release adds one rather than letting a new surface silently fall back to something arbitrary.

Dark mode#

There is no dark-mode switch on Kalendar itself. Dark mode is whatever the colours say it is:

• With KalendarThemeDefaults.colors(), dark mode follows your MaterialTheme.
• With KalendarThemeDefaults.systemColors(), it follows the OS setting.
• With lightColors() / darkColors(), it follows whatever you pass.
• With a hand-built KalendarColors, it follows your own design system.

The other five token sets are mode-independent — sizes, shapes and motion do not change between light and dark — so a single KalendarTheme can swap only colors and leave the rest alone.

Typography#

KalendarTypography covers every piece of text a view draws. Defaults come from MaterialTheme.typography.

To drop the selected/today emphasis entirely, set dayNumberEmphasized equal to dayNumber:

val type = KalendarTheme.typography
KalendarTheme(typography = type.copy(dayNumberEmphasized = type.dayNumber)) {
    KalendarMonth(selectedDate = today)
}

Plugging in a non-Material type scale is the same pattern as colours:

KalendarTheme(
    typography = KalendarThemeDefaults.typography().copy(
        headerTitle = MyTheme.type.heading3,
        dayNumber = MyTheme.type.numeric,
    ),
) {
    KalendarMonth(selectedDate = today)
}

Shapes#

dayCell is one token shared by three separate composables that have to agree visually — the cell, the indicator that animates behind it, and the drag ghost. That is exactly why it lives on the theme rather than on each composable.

KalendarTheme(
    shapes = KalendarTheme.shapes.copy(dayCell = RoundedCornerShape(8.dp)),
) {
    KalendarMonth(selectedDate = today)
}

Dimensions#

Every field of KalendarDimensions has a default, so this is the one token set you can construct from scratch as a one-liner.

Two of these are shared across composables for the same reason shapes.dayCell is: dayCellPadding aligns the cell, the sliding indicator, and the drag ghost; hourGutterWidth sizes both the gutter and the header spacer above it.

KalendarTheme(
    dimensions = KalendarTheme.dimensions.copy(
        hourHeight = 96.dp,
        eventBlockAccentWidth = 0.dp,
    ),
) {
    KalendarSchedule(state = rememberKalendarScheduleState(initialDate = today))
}

Note: KalendarSchedule, KalendarScheduleWeek and KalendarResourceView also take an hourHeight: Dp parameter, which defaults from KalendarDimensions.hourHeight and overrides it for that one calendar. Use the parameter for a single view, the token for every view. KalendarResourceView does the same with minResourceColumnWidth.

Animations#

Every spec is written out in full rather than left to spring()'s defaults, so retuning one is a matter of changing a number rather than of first discovering what the default was. Motion under a finger is a spring — interruptible, and carrying its velocity into whatever interrupts it — while motion that only swaps information is a fixed, short, asymmetric fade: quick to leave, unhurried to arrive. pressScaleSpec is the one spec that bounces, because a press is the only motion a finger is actually resting on.

Reduced motion#

Set enabled = false and every transition becomes instant — the correct response to a platform reduced-motion preference, and what screenshot tests want for determinism:

KalendarTheme(animations = KalendarAnimations(enabled = false)) {
    KalendarMonth(selectedDate = today)
}

Wire it to the platform preference rather than hard-coding it:

KalendarTheme(animations = KalendarAnimations(enabled = !prefersReducedMotion)) {
    KalendarMonth(selectedDate = today)
}

With enabled = false, the selection fill, the press-scale, the event-indicator row, and the header title crossfade all change instantly instead of animating.

To keep motion but soften it, override the individual specs and leave enabled at true:

KalendarTheme(
    animations = KalendarTheme.animations.copy(
        pressScale = 1f,
        titleTransitionMillis = 80,
    ),
) {
    KalendarMonth(selectedDate = today)
}

Strings#

KalendarStrings holds every accessibility announcement and short label. It is a token set like any other, so it is provided through KalendarTheme — see Localization for the full field list and how to feed it your app's resources.

KalendarTheme(
    strings = KalendarStrings(
        previousPage = stringResource(R.string.previous),
        nextPage = stringResource(R.string.next),
        today = stringResource(R.string.today),
    ),
) {
    KalendarMonth(selectedDate = today)
}

Bundling a look with KalendarThemeTokens#

KalendarThemeTokens bundles all six sets into one value, so a whole look can be built once, passed around, and copied:

@Composable
fun rememberBrandKalendarTokens(): KalendarThemeTokens =
    KalendarTheme.tokens.copy(
        colors = KalendarThemeDefaults.systemColors().copy(selectionBackground = BrandPurple),
        shapes = KalendarTheme.shapes.copy(dayCell = RoundedCornerShape(8.dp)),
        animations = KalendarAnimations(enabled = false),
    )

Apply it with the tokens overload, which takes the bundle directly:

KalendarTheme(tokens = rememberBrandKalendarTokens()) {
    KalendarMonth(selectedDate = today)
}

Overriding one calendar#

KalendarTheme(tokens = …) is also how you restyle a single calendar without dressing its surroundings. Where the six-parameter overload is for an app-wide look, this one is for "this one calendar is different": read the ambient bundle from KalendarTheme.tokens, copy only what changes, and everything you did not name keeps coming from the theme above.

KalendarTheme(colors = appCalendarColors) {
    KalendarMonth(selectedDate = today)

    // Compact, but still in the app's colours.
    KalendarTheme(
        tokens = KalendarTheme.tokens.copy(
            dimensions = KalendarDimensions(hourHeight = 32.dp),
        ),
    ) {
        KalendarSchedule(state = rememberKalendarScheduleState(initialDate = today))
    }
}

The override is scoped to the content lambda, so it wins over the enclosing theme and is invisible to siblings. Nesting composes in the obvious direction: the innermost copy wins, and each level above supplies whatever that level did not touch.

tokens is nullable, and null means inherit the surrounding theme untouched — the ambient bundle is passed through by identity, so overriding nothing costs nothing. That is what makes it the right type for a theme-style parameter on a screen of your own:

@Composable
fun BookingScreen(
    bookings: List<Booking>,
    theme: KalendarThemeTokens? = null,
) {
    KalendarTheme(tokens = theme) {
        KalendarMonth(selectedDate = today, events = bookings)
    }
}

Note: the tokens are provided unconditionally, even for a null override. Wrapping conditionally would give the content a different group shape in the two cases, so a caller toggling an override on and off would discard the calendar's remembered state along with it.

Which overload to reach for#

Both provide the same six token sets and nest the same way; tokens simply skips the step of taking a bundle apart into six arguments so the composable can put it back together.

Setting a theme once, app-wide#

Provide the theme high in your tree, next to your own:

@Composable
fun AppTheme(content: @Composable () -> Unit) {
    MaterialTheme(colorScheme = myColorScheme) {
        KalendarTheme(
            shapes = KalendarTheme.shapes.copy(dayCell = RoundedCornerShape(8.dp)),
            dimensions = KalendarTheme.dimensions.copy(dayCellPadding = 4.dp),
            content = content,
        )
    }
}

Because colors and typography are left at their defaults here, they still track the MaterialTheme around them — including its dark-mode switch.

Where to go next#

• Customization — replacing the day cell, header, and event rendering outright.
• Localization — KalendarStrings and the date formatter hooks.
• Configuration — the behavioural knobs that are not tokens.