Activity Graph

Use Activity Graph to show daily activity in a keyboard-accessible calendar heatmap. It accepts ordinary date and value records, handles duplicate days, and keeps the intensity scale useful when values vary widely.

Preview

Reduce motion:Off
Tune:Off
Inspect

920 total activities from January 1, 2026 to June 30, 2026.

920 total activities
LessMore

Installation

Basic usage

TypeScript
activity.tsx

Examples

Use controlled selection when the selected day affects another view. Pass custom metadata and tooltip content when the calendar needs more context than a numeric value.

GitHub data

Fetch GitHub contribution data on the server and pass normalized days into the graph. Keep tokens and API calls outside the component so the installed UI remains safe for client applications.

TypeScript
src/lib/github-contributions.ts

Usage

API

PropertyTypeDefaultDescription
dataActivityGraphDatum[]requiredDated activity records displayed in the graph.
startDateDate | string364 days before endDateInclusive first date displayed by the graph.
endDateDate | stringlatest data date or todayInclusive last date displayed by the graph.
levelsnumber4Number of non-empty color intensity levels.
maxDaysnumber366Maximum number of calendar days rendered.
weekStartsOn0 | 1 | 60First day of each visual week: Sunday, Monday, or Saturday.
valueDate | string | nullundefinedControlled selected date.
defaultValueDate | string | nullundefinedInitially selected date for uncontrolled usage.
onValueChange(date: Date, item: ActivityGraphDatum | undefined) => voidundefinedCalled when a date is selected.
onCellSelect(item: ActivityGraphDatum | undefined, date: Date) => voidundefinedCalled when a selected date is activated with pointer or keyboard.
renderValue(context: ActivityGraphValueContext) => ReactNodeundefinedCustom content shown for the currently explored date.
showValuebooleantrueShows the active date and value above the graph.
showTooltipbooleanfalseShows an anchored tooltip when a date cell is hovered or focused.
tooltipDelaynumber400Delay before the first tooltip opens, in milliseconds.
renderTooltip(context: ActivityGraphValueContext) => ReactNodeundefinedCustom content rendered inside the optional cell tooltip.
colorsstring[]undefinedCustom colors for non-empty intensity levels, ordered from low to high.
emptyColorstringundefinedCustom color for dates without activity.
showMonthLabelsbooleantrueShows month labels above the graph.
showWeekdayLabelsbooleantrueShows abbreviated weekday labels beside the graph.
showLegendbooleantrueShows the intensity legend below the graph.
emptyLabelstring"No activity"Accessible description for a date without activity.
ariaLabelstring"Activity graph"Accessible name for the interactive graph.
gridClassNamestringundefinedAdditional classes for the scrollable graph region.
cellClassNamestringundefinedAdditional classes applied to every date cell.
tooltipClassNamestringundefinedAdditional classes for the optional tooltip surface.
legendClassNamestringundefinedAdditional classes for the intensity legend.

Accessibility

Activity Graph supports roving keyboard focus, visual-direction arrow keys, Home and End, and Enter or Space to select a day. It also provides a range summary and larger coarse-pointer targets.

Styling

The activity-graph token set controls cell size, gaps, radius, colors, and focus treatment. The default range is limited to one year to keep the calendar usable.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Was this page helpful?

Your response helps us improve component docs.