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
920 total activities from January 1, 2026 to June 30, 2026.
Basic usage
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.
Usage
API
| Property | Type | Default | Description |
|---|---|---|---|
data | ActivityGraphDatum[] | required | Dated activity records displayed in the graph. |
startDate | Date | string | 364 days before endDate | Inclusive first date displayed by the graph. |
endDate | Date | string | latest data date or today | Inclusive last date displayed by the graph. |
levels | number | 4 | Number of non-empty color intensity levels. |
maxDays | number | 366 | Maximum number of calendar days rendered. |
weekStartsOn | 0 | 1 | 6 | 0 | First day of each visual week: Sunday, Monday, or Saturday. |
value | Date | string | null | undefined | Controlled selected date. |
defaultValue | Date | string | null | undefined | Initially selected date for uncontrolled usage. |
onValueChange | (date: Date, item: ActivityGraphDatum | undefined) => void | undefined | Called when a date is selected. |
onCellSelect | (item: ActivityGraphDatum | undefined, date: Date) => void | undefined | Called when a selected date is activated with pointer or keyboard. |
renderValue | (context: ActivityGraphValueContext) => ReactNode | undefined | Custom content shown for the currently explored date. |
showValue | boolean | true | Shows the active date and value above the graph. |
showTooltip | boolean | false | Shows an anchored tooltip when a date cell is hovered or focused. |
tooltipDelay | number | 400 | Delay before the first tooltip opens, in milliseconds. |
renderTooltip | (context: ActivityGraphValueContext) => ReactNode | undefined | Custom content rendered inside the optional cell tooltip. |
colors | string[] | undefined | Custom colors for non-empty intensity levels, ordered from low to high. |
emptyColor | string | undefined | Custom color for dates without activity. |
showMonthLabels | boolean | true | Shows month labels above the graph. |
showWeekdayLabels | boolean | true | Shows abbreviated weekday labels beside the graph. |
showLegend | boolean | true | Shows the intensity legend below the graph. |
emptyLabel | string | "No activity" | Accessible description for a date without activity. |
ariaLabel | string | "Activity graph" | Accessible name for the interactive graph. |
gridClassName | string | undefined | Additional classes for the scrollable graph region. |
cellClassName | string | undefined | Additional classes applied to every date cell. |
tooltipClassName | string | undefined | Additional classes for the optional tooltip surface. |
legendClassName | string | undefined | Additional 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.