TimeRanges
Feature

This feature provides an easy way to highlight ranges of time in a calendar's day and week views. Each time range is represented using the TimeRangeModel.

TimeRange types

Time ranges can take a few different forms:

A line at the startDate with optional tooltip based on the name.
A styled region between the startDate and endDate. The cls field is used to apply the desired style to the time range element.
A titled region based on the name field, between the startDate and endDate. The cls field can be used to apply the styling to the time range element. The color and iconCls fields can be used to apply a background color and icon to the header element. An optional footer can also be added.

Disabling the feature will hide all time ranges.

TimeRange DOM structure

A rendered time range element is divided into three sections: a header, body, and footer laid out horizontally across the day cell. This is achieved using flexbox column layout, but rotating the writing-mode to be vertical-rl or vertical-lr so that text is displayed vertically and the primary axis is horizontal.

The time range's cls field is applied to the encapsulating element in addition to the b-cal-time-range class. The arrangement is as follows:

  <inset>px                flexed                 <inset>px
┌────────────┬──────────────────────────────────┬────────────┐
│            │                                  │            │
│     H      │                                  │     F      │
│     e      │                                  │     o      │
│     a      │                                  │     o      │
│     d      │                                  │     t      │
│     e      │                                  │     e      │
│     r      │                                  │     r      │
│            │                                  │            │
└────────────┴──────────────────────────────────┴────────────┘

The visual order can be reversed by setting the alignment field to 'end'.

If the time range has a name, the header section will be rendered with that name and will be inset pixels wide. The header section may also include an icon if the time range has an iconCls field. The header section is rendered with the b-cal-time-range-header CSS class.

The body section occupies the space between the header and footer sections and is rendered with the b-cal-time-range-body CSS class.

If the time range has an footer, a footer section will also be rendered inset pixels wide containing that text. The footer section is rendered with the b-cal-time-range-footer CSS class.

The sections are rendered across the day cell with the name and footer text rotated. The whole element leaves the end gutter area free. To have time ranges render across the gutter area too, apply the CSS class b-cal-time-range-overlay-gutter to a cls time range's cls field.

The body section has no rendition by default, but can be styled using the cls field in addition to the b-cal-time-range-body class.

A header and footer will occupy space on the inline-start and inline-end sides of the time range. This can be reversed by specifying the alignment as 'end'.

The width of the header and footer is determined by the inset configuration of the view's layout.

The three sections of a time range can be customized using the following CSS classes:

.b-cal-time-range-header : The header element
.b-cal-time-range-body : The body element
.b-cal-time-range-footer : The footer element

A "part" renderer can return null to suppress visibility of a header or a footer.

Integration with ScheduleTooltip feature

The ScheduleTooltip feature's renderer will be passed hovered time ranges by default. The content may be customized as in the example below.

Resource-specific TimeRanges

To display time range elements for individual resources, you can include resourceTimeRanges in the loaded data. You can use this feature to visualize resource specific working times for example. The results are shown in views which display resources, such as DayResourceView or subviews of a ResourceView. As with regular time ranges, you can include a recurrenceRule to specify repeating patterns.

Example data showing Resource 1 with shaded days until 9am, and Resource 2 shaded until 8am in the morning.

"resourceTimeRanges" : {
    "rows" : [
      {
        "id"             : 1,
        "resourceId"     : 1,
        "startDate"      : "2026-01-26 00:00",
        "endDate"        : "2026-01-26 09:00",
        "recurrenceRule" : "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
      },
      {
        "id"             : 2,
        "resourceId"     : 2,
        "startDate"      : "2026-01-26 00:00",
        "endDate"        : "2026-01-27 08:00",
        "recurrenceRule" : "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
      }
   ]
}

This feature is disabled by default.

Useful configs

Config	Description
renderer	Custom renderer for time range elements
headerWidth	Width of the time range header area (pixels or proportion)

Configs

Configs are options you supply in a configuration object when creating an instance of this class

headerWidth : Number40

The number of pixels or proportion of the overall width to allocate for time range headers.

Values less than 1 are the fractional proportion of the width (for example, 0.04 is 4% of the width), while values greater than or equal to 1 are a number of pixels.
renderer : Function/TimeRangeRenderer
An empty function by default, but provided so that you can override it.

This function is called each time a time range is rendered to allow developers to mutate the element metadata, or the CSS classes to be applied to the rendered element.

It's called with a TimeRangeRenderInfo object containing the time span record, and a renderData object which allows you to mutate event metadata such as cls and style.

A non-null return value from the renderer is used as the element body content. A nullish return value results in the default renderer for the element.
```
 timeRanges : {
     renderer ({ timeRange, renderData }) {
         if (timeRange.name === 'Doctors appointment') {
             renderData.style.fontWeight = 'bold';
             renderData.cls['custom-cls'] = 1;

             return 'Special doctors appointment';
         }
     }
 }
```
When returning content, be sure to consider how that content should be encoded to avoid XSS (Cross-Site Scripting) attacks. This is especially important when including user-controlled data such as the event's `name`. The function encodeHtml as well as xss can be helpful in these cases.

For example:
```
 timeRanges : {
     renderer ({ timeRange, renderData }) {
         return StringHelper.xss`Special ${timeRange.name}`;
     }
 }
```
For advanced rendering, this config can be a TimeRangeRenderer object with rendering functions for individual elements: header, body, footer, and outer. When a function is provided, that is equivalent to passing the header renderer. In other words, the above example is equivalent to the following:
```
 timeRanges : {
     renderer : {
         header({ timeRange, renderData }) {
             return StringHelper.xss`Special ${timeRange.name}`;
         }
     }
 }
```
Note that if the TimeRange has zero duration, it will be rendered as a line, and the header, body and footer renderers will not add any content. The outer renderer may mutate the domConfig property to affect how the line will be rendered.
Parameters
- info : TimeRangeRenderInfo
  
  An object that contains data about the time span being rendered.
Returns

String

Properties

Properties are getters/setters or publicly accessible variables on this class

isTimeRanges : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of TimeRanges class, or subclass thereof.

isTimeRanges : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of TimeRanges class, or subclass thereof.

Type definitions

TimeRangeRenderData
A mutable object used to render an element of the time range.
Properties
- record : TimeRangeModel
  
  The record being rendered
- isLine : Boolean
  
  This is true if the TimeRange has zero duration, meaning it will be rendered as a line with no header, body or footer.
- color : String
  
  The color to be applied to the element
- cls : Object
  
  An object whose truthy property names will be added to the element's CSS classList
- style : Object
  
  An object containing style properties for the element
- outer : TimeRangeRenderData
  
  The render data for the outermost element. This property is present when rendering any of the inner elements. The outer element is rendered after all inner elements, meaning this object can be modified by an inner element renderer function.
- header : TimeRangeRenderData
  
  The render data for the header element. This property is present when rendering the outermost element. The corresponding element has already been rendered, meaning that this object should be considered read only.
- body : TimeRangeRenderData
  
  The render data for the body element. This property is present when rendering the outermost element. The corresponding element has already been rendered, meaning that this object should be considered read only.
- footer : TimeRangeRenderData
  
  The render data for the footer element. This property is present when rendering the outermost element. The corresponding element has already been rendered, meaning that this object should be considered read only.
TimeRangeRenderInfo
The object passed to a renderer function.
Properties
- renderData : TimeRangeRenderData
  
  The render data object to modify
- timeRange : TimeRangeModel
  
  The record being rendered
- domConfig : DomConfig
  
  The default DOM config. This is only passed to the outer renderer and represents the DOM config that will be used for the element. The className and style properties are applied after the renderer returns.
TimeRangeRenderer
An object containing rendering methods for the various elements of a time range. All functions are optional. The footer function is special in that there is no footer element by default. If a footer is desired, a footer renderer function must be provided.
Properties
- outer : Function
  
  An optional function to be called to render the outermost element. This function is passed a TimeRangeRenderInfo object.
- body : Function
  
  An optional function to be called to render the body element. This function is passed a TimeRangeRenderInfo object.
- header : Function
  
  An optional function to be called to render the header element. This function is passed a TimeRangeRenderInfo object.
- footer : Function
  
  An optional function to be called to render the footer element. This function is passed a TimeRangeRenderInfo object.

CSS variables

CSS variables that can be set to adjust appearance

Name	Description
--b-calendar-time-range-border-color	Time range border color
--b-calendar-time-range-border-width	Time range border width
--b-calendar-time-range-header-background	Time range header background
--b-calendar-time-range-line-size	Time range line size
--b-calendar-time-range-line-zoom-scale	Time range line zoom scale

id: timeRanges

Source path

Calendar/feature/TimeRanges.js

Demo

examples/timeranges

TimeRanges
Feature

TimeRange types

TimeRange DOM structure

Integration with ScheduleTooltip feature

Resource-specific TimeRanges

Useful configs

See also

Configs

Parameters

Returns

Properties

Type definitions

Properties

Properties

Properties

CSS variables

Source path

Demo

Inheritance tree5

Mixins3

Contents

TimeRanges Feature

TimeRange types

TimeRange DOM structure

Integration with ScheduleTooltip feature

Resource-specific TimeRanges

Useful configs

See also

Configs

Parameters

Returns

Properties

Type definitions

Properties

Properties

Properties

CSS variables

Source path

Demo

Inheritance tree5

Mixins3

Contents

TimeRanges
Feature