Time Band Documentation

A Time Band highlights a period across the timeline. Use it to add contextual date ranges, configure band data and styles, and manage bands at runtime.

Time Band Schema Since v1.3

Time bands describe the spans rendered behind the main timeline line. They use the same millisecond-to-billion-year precision model as articles.

At a glance: Required fields — id, title, from.

Schema 
// Time Band Schema (clickable)
{
  id: /* required: number|string */,
  title: /* required: string */,

  from: {
    year: /* required: number */,
    month: /* optional: 1-12 */,
    day: /* optional: 1-31 */,
    hour: /* optional: 0-23; default: 0 */, // Since v1.6
    minute: /* optional: 0-59; default: 0 */, // Since v1.6
    second: /* optional: 0-59; default: 0 */, // Since v1.6
    millisecond: /* optional: 0-999; default: 0 */, // Since v1.6
    precision: /* optional: inferred from supplied time fields; otherwise 'day' */
  },

  to: { /* optional */
    year: /* required: number */,
    month: /* optional: 1-12 */,
    day: /* optional: 1-31 */,
    hour: /* optional: 0-23; default: 0 */, // Since v1.6
    minute: /* optional: 0-59; default: 0 */, // Since v1.6
    second: /* optional: 0-59; default: 0 */, // Since v1.6
    millisecond: /* optional: 0-999; default: 0 */, // Since v1.6
    precision: /* optional: same inference and precision strings as from */
  },
  isToPresent: /* optional: boolean; default: false */,

  style: /* optional: TimeBandStyle */,
  visibility: /* optional: 'visible' (default) | 'hidden' | function(TimeBand): 'visible' | 'hidden' */
};
Precision defines the visible range. Omitted precision is inferred from the finest supplied time component: millisecond, second, minute, then hour. Zero counts as supplied. With no time components it defaults to 'day', including year-only and year/month objects. Explicit precision is authoritative, so finer fields are ignored. A from-only band at millisecond precision covers that exact millisecond; second precision ends in .999; minute precision ends in :59.999; and hour precision ends in :59:59.999. Time fields are timezone-free calendar positions, not JavaScript Date timestamps. See Dates and Dmy for the shared date model and its relationship to precision.

Time Band Options Since v1.3

Control visibility, layout, and defaults for background eras rendered behind the main timeline line.

These options live under options.timeBand.*. The values shown below are the defaults.

JavaScript 
// Time Band options (defaults)
{
  visible: true,
  reserveSpace: true,
  reserveSpacePixels: 20,
  area: { up: 0, down: 'edge' },
  defaultStyle: { /* see Time Band Style */ },
  data: [ /* see Time Band Schema */ ]
};

Time Band Style Since v1.3

Customize the palette, borders, and typography applied to every band. Per-band overrides merge deeply with this default object.

timeBand.defaultStyle in the Time Band Options object.

JavaScript 
// Time Band defaultStyle
{
  backgroundColor: 'rgba(200, 200, 200, 0.25)',
  border: {
    color: 'rgba(120, 120, 120, 0.25)',
    width: 1
  },
  text: {
    font: 'normal 16px Calibri',
    color: '#555',
    align: 'left',
    baseline: 'bottom',
    verticalAlign: 'bottom',
    margin: 4,
    offsetY: 0
  }
};

Per-band overrides: call band.setStyle, or set the style key in the Time Band data with a partial object. Fields you omit fall back to the defaults above.

Time Band Methods Since v1.3

Option and style setters accept Histropedia.UNSET in dot paths or sparse object patches to remove an override and restore its applicable default or inherited value.

Manage broad eras and background spans after your timeline is initialized.

Tip: Loaded bands are stored as TimeBand instances in timeline.timeBands. TimeBand is also exported as Histropedia.TimeBand for UMD and as a named ESM export.

.setOption(option, value?) New values

Configuration

Update Time Band data fields using objects or dot-notation paths.

Parameters

option string | object

Full band object for batch updates, or a dot-notation path such as 'to.year'.

value any

New value when using a string path. Omit this argument to read the current value.

Returns

any – Current value when called as a getter; otherwise void.

Use this method for making changes to Time Band data fields after they have been loaded. The available fields are defined in the Time Band Schema. 

const band = timeline.timeBands.find(b => b.id === 2);

// Batch update fields
band.setOption({
  title: 'Reagan Presidency',
  to: { year: 1989, month: 1, day: 20, precision: 'day' }
});

// Read the current end date
const end = band.setOption('to');

.setStyle(option, value?) New values

Styling

Override the visual style for a specific band or query an override value.

Parameters

option string | object

Partial style object or dot-notation path (e.g. 'text.color').

value any

New value when using a string path. Omit to read the current override.

Returns

any – Current override value when reading; otherwise void.

Overrides merge deeply with timeBand.defaultStyle, so supply only the properties you want to change.

const spotlight = timeline.timeBands.find(b => b.id === 3);

// Update a single field
spotlight.setStyle('backgroundColor', 'rgba(12, 74, 110, 0.35)');

// Apply multiple overrides
spotlight.setStyle({
  text: {
    color: '#0f172a',
    align: 'center'
  }
});

// Read the current override
const labelColor = spotlight.setStyle('text.color');

Need More Help?

If you can't find what you're looking for, browse the examples or contact us.

Contact Support Browse Examples