Week Planner
Weekly schedule with time blocks: a typical week with optional odd and even weeks, or a dated week the user edits.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
events | WeekPlannerEvent[] | [] | The plan: { id?, title, day?, date?, start, end, weeks?, color? } entries. Accepts a JSON string as an attribute. |
date | string | — | Shows the calendar week holding this date, YYYY-MM-DD (any day of the week). Empty — the default — shows a
typical week without dates. The header navigation updates it. |
editable | boolean | false | Lets the user add events by clicking an empty spot and move or resize them by dragging; see slot-click and event-change. |
snap-minutes | number | 30 | Step, in minutes, that slot-click times, drags and keyboard moves snap to. |
alternate-weeks | boolean | false | Honours each event's weeks and shows the Odd week | Even week switch. Off by default: every event shows each week. |
parity | WeekPlannerParity | '' | — | Kind of week shown with alternate-weeks. Defaults to the kind of the current ISO week. |
start-hour | number | 8 | First hour on the scale; earlier events extend it. |
end-hour | number | 18 | Last hour on the scale; later events extend it. |
week-start | WeekPlannerWeekStart | '' | — | First day of the week. Defaults to the convention of locale (Sunday in en-US, Monday in fr or en-GB). |
locale | string | — | Language of the planner's text and day names, e.g. fr or en-GB. Defaults to the nearest lang, else the browser's language. |
heading | string | — | Title shown at the start of the header, e.g. "Kids' schedule". It also names the planner for assistive technology. |
aria-label | string | null | null | Accessible name for the planner. Defaults to heading, else "Week plan" in the planner's language. |
Slots
| Name | Description |
|---|---|
heading | Title at the start of the header, in place of the heading text. It names the planner unless heading or aria-label is set. |
actions | Controls at the end of the header, before the previous/next arrows, e.g. an "Add event" button. |
Events
| Name | Type | Description |
|---|---|---|
parity-change | CustomEvent<WeekPlannerParityChangeDetail> | Fired when the switch shows the other kind of week; detail.parity is odd or even. |
week-change | CustomEvent<WeekPlannerWeekChangeDetail> | Fired when the header navigation of a dated planner shows another week; detail.start and detail.end are its first and last day as YYYY-MM-DD. Does not bubble. |
event-click | CustomEvent<WeekPlannerEventClickDetail> | Fired when an event block is activated; detail.event is the entry from events. |
slot-click | CustomEvent<WeekPlannerSlotClickDetail> | With editable, fired when an empty spot or a day's "New event" button is activated: { day, date?, start, end }, start snapped to snap-minutes and end an hour later. Add the event to events yourself. |
event-change | CustomEvent<WeekPlannerEventChangeDetail> | With editable, fired when an event is dropped after a drag or moved/resized from the keyboard: { event, changes }, event the original entry and changes its new start, end and day or date. Update events yourself. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
heading | Heading region wrapping the heading slot and the heading text fallback; assigned content keeps its own styles. |
actions | Actions region wrapping the actions slot at the end of the header, before the previous/next arrows; assigned controls keep their own styles. |
event | Each event block. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-week-planner--background | color | #ffffff | |
--c2-week-planner--color | color | #18181b | |
--c2-week-planner--border | border | 1px solid #e4e4e7 | |
--c2-week-planner--border-radius | border-radius | 8px | |
--c2-week-planner--padding | padding | 12px | |
--c2-week-planner--font-family | font-family | inherit | |
--c2-week-planner--font-size | font-size | 14px | |
--c2-week-planner__title--font-size | font-size | 14px | The heading. |
--c2-week-planner__title--font-weight | font-weight | 600 | |
--c2-week-planner__grid--border | border | 1px solid #e4e4e7 | Lines between the day columns. |
--c2-week-planner__hour--border | border | 1px solid rgba(24, 24, 27, 0.06) | Line under each hour. Translucent, so it stays visible over today's tint. |
--c2-week-planner__hour--height | pixel | 48px | |
--c2-week-planner__hour-label--width | pixel | 48px | |
--c2-week-planner__hour-label--color | color | #71717a | |
--c2-week-planner__hour-label--font-size | font-size | 11px | |
--c2-week-planner__actions--gap | pixel | 8px | Space between the controls in the actions slot. |
--c2-week-planner__navigation--size | pixel | 28px | Previous/next day arrows, shown when the planner is too narrow for seven days. |
--c2-week-planner__navigation--border-radius | border-radius | 6px | |
--c2-week-planner__navigation__hover--background | color | #f4f4f5 | |
--c2-week-planner__day-header--color | color | #71717a | |
--c2-week-planner__day-header--font-size | font-size | 12px | |
--c2-week-planner__day-header__today--color | color | rgb(2, 101, 220) | |
--c2-week-planner__day-header__today--font-weight | font-weight | 600 | |
--c2-week-planner__day__today--background | color | rgba(2, 101, 220, 0.05) | Tint of today's column. |
--c2-week-planner__now--color | color | #dc2626 | Line at the current time. |
--c2-week-planner__event--background | color | rgb(2, 101, 220) | Block colour of an event without its own color. |
--c2-week-planner__event--color | color | #ffffff | |
--c2-week-planner__event--border-radius | border-radius | 4px | |
--c2-week-planner__event--font-size | font-size | 12px | |
--c2-week-planner__event--font-weight | font-weight | 500 | |
--c2-week-planner__event__hover--opacity | opacity | 0.88 | |
--c2-week-planner__event__dragging--opacity | opacity | 0.4 | The event being dragged, at its original place. |
--c2-week-planner__focus--outline | outline | 2px solid rgba(2, 101, 220, 0.4) | |
--c2-week-planner__focus--outline-offset | pixel | 2px | |
--c2-week-planner__week-title--color | color | #71717a | The dated week's range in the header. |
--c2-week-planner__week-title--font-size | font-size | 14px | |
--c2-week-planner__day-number--font-weight | font-weight | 600 | Day of the month in a dated week's day headers. |
--c2-week-planner__slot__hover--background | color | rgba(2, 101, 220, 0.1) | With editable, the hour under the pointer in an empty spot. |
--c2-week-planner__preview--border | border | 2px dashed rgb(2, 101, 220) | Where a dragged event would land, and the focused "New event" button. |
--c2-week-planner__preview--background | color | rgba(2, 101, 220, 0.1) | |
--c2-week-planner__preview--color | color | rgb(2, 101, 220) | |
--c2-week-planner__resize-handle--height | pixel | 6px | With editable, the strip at the bottom of a block that resizes it. |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under week-planner, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide. Built in besides English: fr, de, es, it, pt, nl, vi; an app can override them.
| Key | English | Values |
|---|---|---|
odd | Odd week | — |
even | Even week | — |
kind | Kind of week | — |
plan | Week plan | — |
previous | Previous days | — |
next | Next days | — |
previousWeek | Previous week | — |
nextWeek | Next week | — |
add | New event | — |