Year View

A year of days shaded by how much happened on each.

Source
$npx @dinachi/cli@latest add year-view
1,119 deploys in the last 12 months

layout
disabled

Usage

import { useState } from "react"
import { YearView } from "@/components/ui/year-view"

export function Deploys({ counts }: { counts: Record<string, number> }) {
  const [day, setDay] = useState<Date | null>(null)
  return <YearView aria-label="Deploys" counts={counts} value={day} onValueChange={setDay} />
}

Examples

1,119 deploys in the last 12 months

A year of deploys. Picking a day shows its count.
import { useState } from 'react';
import { YearView } from '@/components/ui/year-view';

export function Example({ counts }: { counts: Record<string, number> }) {
  const [day, setDay] = useState<Date | null>(null);
  return (
    <YearView
      aria-label="Deploys"
      counts={counts}
      value={day}
      onValueChange={setDay}
      formatCount={(n) => `${n.toLocaleString("en-US")} ${n === 1 ? "deploy" : "deploys"}`}
    />
  );
}

Notes

Server rendering

Pass today when the page renders on a server, so the server and the browser agree on which day it is.

Color

The shades mix --success into --muted. Set --year-view-color on the view, or any parent, to shade with another color.

Weeks and months

The weeks layout fits a year across a desktop and scrolls to the latest week. On a phone the months layout stacks months latest first, so days are big enough to tap.

API

countsRecord<string, number>
How many things happened each day, keyed YYYY-MM-DD.
value
agent
Date | null
The picked day.
defaultValueDate | null
Starting day when uncontrolled.
onValueChange
agent
(value, details) => void
Runs on every pick, for people and agents. details.cancel() refuses the change.
end
agent
Date = today
The last day shown.
start
agent
Date
The first day shown. The view covers as many weeks as start to end takes. Defaults to the 53 weeks up to end's week.
max
agent
Date = today
The last day that can be picked. Set it past today for days ahead, such as bookings.
requiredboolean = false
Pressing the picked day keeps it instead of clearing it, and an agent can't clear it.
thresholds[number, number, number, number]
Counts at or above each step get shades 1 to 4. Defaults to quarters of the busiest day.
formatCount(count: number) => string = "3 events"
How a count reads in the heading, the readout and each day's name.
heading(total: number) => ReactNode
The line above the grid. Defaults to the total for the year shown.
layout"auto" | "weeks" | "months" = "auto"
Weeks side by side, or months stacked with squares big enough to tap. auto switches at 768px. Months scroll inside a box --year-view-height tall, 22rem by default.
localeLocale
A date-fns locale for day and month names and the first day of the week.
weekStartsOn0 to 6 = 1
The first day of the week, 0 for Sunday. Defaults to the locale's.
dir"ltr" | "rtl"
Reading direction. Arrow keys follow it.
today
agent
Date
Overrides the current day. Without max, days after it are outlined and can't be picked.
disabled
agent
boolean = false
Blocks people and agents.
namestring
Submits the picked day as YYYY-MM-DD.

Agent

Inside an AgentProvider, it appears in agent.snapshot() as date.

Reads

label

The aria-label, "Activity" by default.

value

The picked day as YYYY-MM-DD, or absent.

Actions

setValue("2026-11-11")

Picks a day.

clear()

Clears the pick. Refused when required is set.

An agent's change runs through onValueChange like anyone's. isAgentChange(details) is true for it; details.cancel() refuses it. A day before the view starts, or after max or end, is refused with the reason.

await agent.act({
  steps: [{ ref: "Deploys", action: "setValue", args: ["2026-11-11"] }],
})

Accessibility

  • Each day is a toggle button named with its date and count, such as Wednesday 11 November 2026: 8 events.
  • Days before start, or after max or end, have aria-disabled. Only one day is in the tab order.
  • Shade is never the only signal: every count is in the day's name and in the readout. Only the top shade reaches 3:1 against the page, so don't rely on the lighter ones to carry meaning.
  • The readout is a live region.