- Examples
- Booking calendar
- Team calendar
- Room booking
- Shift scheduler
- Conference agenda
- Calendar in an app layout
- Optimistic server sync
- Lazy-load by date range
- View and date in the URL
- Custom persistence adapter
- ICS import and export
- Custom event rendering
- Multiple time zones
- Linked month and day views
- Recurring events (RRULE)
- Custom ⌘K commands
- Natural-language event entry
Calendar in an app layout
The calendar as one route of a product — sidebar nav, a header built from useKloq(), and a container that gives it a real height.
A mock product: a sidebar with four routes, "Calendar" active, and the calendar filling the rest. The header is the product's — its title, ‹ › Today, a view switcher, Share and an avatar — but every control in it reads the calendar it sits inside. Step the range and the heading changes.
live·Calendar in an app layout
"use client";
import { Avatar, AvatarFallback } from "@coss/ui/components/avatar";
import { Button } from "@coss/ui/components/button";
import { Kloq, type KloqView, useKloq } from "kloq";
import { BarChart3, CalendarDays, FolderKanban, Inbox, Share2 } from "lucide-react";
import { useState } from "react";
import { SegmentedControl, SegmentedControlItem } from "@/components/calendar/ui/segmented-control";
import { Nav } from "../parts";
import { shellEvents } from "./data";
const NAV = [
{ label: "Inbox", icon: Inbox },
{ label: "Projects", icon: FolderKanban },
{ label: "Calendar", icon: CalendarDays, active: true },
{ label: "Reports", icon: BarChart3 },
];
const VIEWS: { view: KloqView; label: string }[] = [
{ view: "day", label: "Day" },
{ view: 3, label: "3 days" },
{ view: "week", label: "Week" },
{ view: "month", label: "Month" },
];
/** The product's page header, fed by the calendar it sits inside. */
function Header() {
const k = useKloq();
return (
<Kloq.Toolbar>
<Nav />
<div className="flex flex-wrap items-center gap-2">
<SegmentedControl
size="sm"
aria-label="View"
value={k.viewSetting}
onValueChange={k.switchView}
>
{VIEWS.map(({ view, label }) => (
<SegmentedControlItem key={label} value={view} disabled={!(k.fits?.(view) ?? true)}>
{label}
</SegmentedControlItem>
))}
</SegmentedControl>
<Button variant="outline" size="sm">
<Share2 />
Share
</Button>
<Avatar>
<AvatarFallback>SK</AvatarFallback>
</Avatar>
</div>
</Kloq.Toolbar>
);
}
export default function AppShellExample() {
const [events] = useState(() => shellEvents(new Date()));
return (
<div className="@container flex flex-col">
<div className="flex h-136">
<aside className="hidden w-44 shrink-0 flex-col border-r bg-muted/32 @2xl:flex">
<p className="flex items-center gap-2 px-4 py-3.5 font-heading text-sm font-semibold">
<span aria-hidden className="size-2 rounded-xs bg-brand" />
Orbit
</p>
<nav aria-label="Orbit" className="flex flex-col gap-0.5 px-2">
{NAV.map(({ label, icon: Icon, active }) => (
<Button
key={label}
variant="ghost"
size="sm"
className="justify-start aria-[current=page]:bg-accent"
aria-current={active ? "page" : undefined}
>
<Icon />
{label}
</Button>
))}
</nav>
<p className="mt-auto border-t px-4 py-3 font-mono text-xs text-muted-foreground">
acme · 12 seats
</p>
</aside>
<div className="min-w-0 flex-1">
<Kloq
defaultEvents={events}
defaultView={3}
persistence={false}
designMode={false}
storage={false}
>
<Header />
</Kloq>
</div>
</div>
</div>
);
}
import { type CalEvent, type EventColor, instantAt, resolveView } from "kloq";
interface Slot {
title: string;
/** days from today, minutes from midnight, length in minutes */
day: number;
at: number;
minutes: number;
color: EventColor;
location?: string;
}
const h = (hours: number, minutes = 0) => hours * 60 + minutes;
const WEEK: Slot[] = [
{ title: "Standup", day: 0, at: h(9), minutes: 15, color: "blue" },
{ title: "Design crit", day: 0, at: h(11), minutes: 60, color: "violet", location: "Room 4" },
{ title: "Lunch", day: 0, at: h(12, 30), minutes: 45, color: "emerald" },
{ title: "Ship v2.3", day: 0, at: h(15), minutes: 90, color: "amber" },
{ title: "Standup", day: 1, at: h(9), minutes: 15, color: "blue" },
{ title: "1:1 with Priya", day: 1, at: h(10), minutes: 30, color: "blue" },
{ title: "Customer call", day: 1, at: h(14), minutes: 45, color: "rose" },
{ title: "Standup", day: 2, at: h(9), minutes: 15, color: "blue" },
{ title: "Roadmap review", day: 2, at: h(13), minutes: 90, color: "violet" },
{ title: "Retro", day: 2, at: h(16), minutes: 45, color: "emerald" },
];
/** Three days of a product team's week, from today. */
export function shellEvents(now: Date): CalEvent[] {
const view = resolveView(3, 1, now);
return WEEK.map((s, i) => ({
id: `shell-${i}`,
title: s.title,
color: s.color,
location: s.location,
start: instantAt(view, s.day, s.at),
end: instantAt(view, s.day, s.at + s.minutes),
}));
}
"use client";
import { Button } from "@coss/ui/components/button";
import { cn } from "@coss/ui/lib/utils";
import { formatViewTitle, useIsClient, useKloq } from "kloq";
import { ChevronLeft, ChevronRight } from "lucide-react";
import type { ComponentProps } from "react";
/** The strip an example hangs its controls and readouts on; same box as `Kloq.Toolbar`. */
export function Bar({
edge = "bottom",
className,
...props
}: ComponentProps<"div"> & { edge?: "top" | "bottom" }) {
return (
<div
{...props}
className={cn(
"flex min-h-11 shrink-0 flex-wrap items-center gap-x-4 gap-y-2 px-4 py-2.5 font-mono text-xs text-muted-foreground",
edge === "bottom" ? "border-b" : "border-t",
className,
)}
/>
);
}
export function Dot({ live, className, ...props }: ComponentProps<"span"> & { live?: boolean }) {
return (
<span
aria-hidden
{...props}
className={cn(
"size-1.5 shrink-0 rounded-full",
live ? "bg-brand motion-safe:animate-pulse" : "bg-border",
className,
)}
/>
);
}
/** Previous / next / today for a calendar whose view is fixed. Must render inside `<Kloq>`. */
export function Nav({ locale }: { locale?: string }) {
const k = useKloq();
const isClient = useIsClient();
return (
<div className="flex min-w-0 items-center gap-1">
<Button variant="ghost" size="icon-xs" aria-label="Previous" onClick={() => k.step(-1)}>
<ChevronLeft />
</Button>
<Button variant="ghost" size="icon-xs" aria-label="Next" onClick={() => k.step(1)}>
<ChevronRight />
</Button>
<Button
variant="ghost"
size="xs"
className={cn(k.atToday && "text-muted-foreground")}
onClick={k.goToday}
>
Today
</Button>
<span className="ms-1 truncate text-sm font-medium text-foreground tabular-nums sm:text-xs">
{isClient ? formatViewTitle(k.view, locale, { short: k.narrow }) : null}
</span>
</div>
);
}
useschildrenuseKloqKloq.ToolbarfitsswitchView
How it works
The shell is a flex row with a real height: flex h-136. The sidebar is a
fixed w-44 that only appears once the frame is wide enough (hidden @2xl:flex — a container query, so it follows the box, not the window), and
the calendar's cell is min-w-0 flex-1, so the row, not its content, decides
its size. <Kloq> — which is h-full and never reaches for the window —
fills it. That is the whole of
"the container is the contract":
give the component a box with a height and it renders into it.
<Kloq> renders no app bar of its own. Header is passed as children, so
it lands above the surface inside the calendar's provider, and it calls
useKloq() for everything it shows: Nav (in parts.tsx) reads view
for the title via formatViewTitle and step / goToday / atToday for
the range controls; the segmented control reads viewSetting and calls
switchView. Kloq.Toolbar is only the
bordered row. See toolbar & chrome.
The calendar measures its own cell, not the window. At full width the cell
is about 730px: the stock
responsive collapse leaves three days
alone there and turns a seven-column week into three. Narrow the frame until
the sidebar drops away and the cell falls under 640px, where the collapse
shows a single day. The switcher disables what does not fit with
k.fits(view), the same call the built-in switcher makes. For an app column
that is narrower by design, responsive={{ breakpoint }} moves that tier.
Nothing in the sidebar knows about the calendar. It is plain markup outside
<Kloq>, which is where product chrome that does not need calendar state
belongs.
Take it further
Move view and date into your router and pass them as controlled props —
View and date in the URL does exactly that — and
the header keeps working unchanged, because useKloq() reports the effective
state either way.
Last updated
On This Page