Grouped Time Headers

Grouped time headers add several label columns beside the Calendar's vertical time axis. Combine day and hour labels for a multi-day resource calendar, or label individual lesson periods in a timetable.

Available in DayPilot Pro for JavaScript, including Angular, React and Vue, from 2026.4.7150.

Define Header Levels

Set timeHeaders to an array. Each item defines one level with its own groupBy, date format and pixel width. Levels are ordered from index zero in array order; there is no fixed maximum number of levels.

The example adds day and hour columns to a resource calendar and hides non-business intervals. The day labels use an 80-pixel column and the hour labels use 60 pixels. The callback styles the day level and leaves the hour level's default labels intact. These examples configure an existing Calendar; retain its events and other application settings.

JavaScript

const calendar = new DayPilot.Calendar("dp", {
  startDate: "2028-04-03",
  viewType: "Resources",
  days: 7,
  columns: [{id: "A", name: "Cedar room"}],
  scale: "Hour",
  showNonBusiness: false,
  timeHeaders: [
    {groupBy: "Day", format: "ddd M/d", width: 80},
    {groupBy: "Hour", format: "H:mm", width: 60}
  ],
  onBeforeTimeHeaderRender: args => {
    if (args.header.level === 0) {
      args.header.backColor = "#e8eef5";
      args.header.fontColor = "#33465c";
      args.header.horizontalAlignment = "center";
    }
  }
});
calendar.init();

Angular

<daypilot-calendar [config]="config"></daypilot-calendar>

import {DayPilot} from "daypilot-pro-angular";

config: DayPilot.CalendarConfig = {
  startDate: "2028-04-03",
  viewType: "Resources",
  days: 7,
  columns: [{id: "A", name: "Cedar room"}],
  scale: "Hour",
  showNonBusiness: false,
  timeHeaders: [
    {groupBy: "Day", format: "ddd M/d", width: 80},
    {groupBy: "Hour", format: "H:mm", width: 60}
  ],
  onBeforeTimeHeaderRender: args => {
    if (args.header.level === 0) {
      args.header.backColor = "#e8eef5";
      args.header.fontColor = "#33465c";
      args.header.horizontalAlignment = "center";
    }
  }
};

React

import {DayPilot, DayPilotCalendar} from "daypilot-pro-react";

<DayPilotCalendar
  startDate="2028-04-03"
  viewType="Resources"
  days={7}
  columns={[{id: "A", name: "Cedar room"}]}
  scale="Hour"
  showNonBusiness={false}
  timeHeaders={[
    {groupBy: "Day", format: "ddd M/d", width: 80},
    {groupBy: "Hour", format: "H:mm", width: 60}
  ]}
  onBeforeTimeHeaderRender={args => {
    if (args.header.level === 0) {
      args.header.backColor = "#e8eef5";
      args.header.fontColor = "#33465c";
      args.header.horizontalAlignment = "center";
    }
  }}
/>

Vue

<script setup lang="ts">
import {DayPilot, DayPilotCalendar} from "daypilot-pro-vue";
const columns: NonNullable<DayPilot.CalendarConfig["columns"]> = [{id: "A", name: "Cedar room"}];
const timeHeaders: NonNullable<DayPilot.CalendarConfig["timeHeaders"]> = [
    {groupBy: "Day", format: "ddd M/d", width: 80},
    {groupBy: "Hour", format: "H:mm", width: 60}
  ];
const onBeforeTimeHeaderRender: NonNullable<DayPilot.CalendarConfig["onBeforeTimeHeaderRender"]> = args => {
    if (args.header.level === 0) {
      args.header.backColor = "#e8eef5";
      args.header.fontColor = "#33465c";
      args.header.horizontalAlignment = "center";
    }
  };
</script>

<template>
  <DayPilotCalendar
    startDate="2028-04-03"
    viewType="Resources"
    :days="7"
    :columns="columns"
    scale="Hour"
    :showNonBusiness="false"
    :timeHeaders="timeHeaders"
    :onBeforeTimeHeaderRender="onBeforeTimeHeaderRender"
  />
</template>

Grouping and Labels

The header grouping is independent of the grid scale. Use calendar units such as "Day" and "Hour" to identify dates and times. Use "Cell" to follow individual visible cells, including periods with different durations in a manual timeline. "None" creates one unlabeled interval over the displayed range.

Each level's format uses DayPilot.Date.toString() formatting. See timeHeaders for all grouping values.

Column Widths

A level's width overrides hourWidth. Omit the level width to inherit hourWidth. The total header width is the sum of all level widths: 140 pixels in the example. See also Time Header Column Width for the default time-header column.

Customize a Level

Use onBeforeTimeHeaderRender and the zero-based args.header.level to select a level, as in the example. The header also provides its groupBy, full start date and exclusive end.

Set html for custom content or cssClass for CSS styling. Set text as well when supplying custom HTML so image export has a meaningful plain-text label. See Time Header Customization for examples that use the default time headers.

Hidden Intervals and Default Time Headers

Grouped labels follow the retained timeline. Nights, weekends and other omitted intervals take no header height. See Hiding Non-Business Time.

Omit timeHeaders to use the default time headers. Setting it to null restores them in JavaScript. The default time headers use timeHeaderCellDuration for grouping; explicit grouped headers use their own groupBy and format instead. An empty array displays no levels. showHours can hide the entire time-header area.

In the header-render callback, args.header.date is null for default time headers in Day and Week views. Grouped headers and Resources headers provide a full date.