HistropediaJS Time Band Documentation

Time Band Schema new

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 */, // new
    minute: /* optional: 0-59; default: 0 */, // new
    second: /* optional: 0-59; default: 0 */, // new
    millisecond: /* optional: 0-999; default: 0 */, // new
    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 */, // new
    minute: /* optional: 0-59; default: 0 */, // new
    second: /* optional: 0-59; default: 0 */, // new
    millisecond: /* optional: 0-999; default: 0 */, // new
    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' */
};

JavaScript

// Minimal Time Band
{
  id: 1,
  title: "Middle Ages",
  from: { year: 500 },
  to:   { year: 1500 }
}

JavaScript

// Full Time Band example
{
  id: 2,
  title: "Industrial Revolution",
  from: { year: 1760, month: 1, day: 1 },
  to:   { year: 1840, precision: 'year' },
  isToPresent: false,

  style: {
    backgroundColor: 'rgba(14, 165, 233, 0.2)',
    border: { color: 'rgba(14, 165, 233, 0.45)', width: 2 },
    text: { color: '#0ea5e9', align: 'center', font: '600 16px Calibri' }
  },
  visibility: (band) => band.owner.getZoom() >= 20 ? 'visible' : 'hidden'
}

`id` string | number

Unique identifier used when updating or replacing a band.

`title` string

Label displayed on the band. Required for text to render.

`from` DateInput

Start of the band. Provide year and optionally month, day, hour, minute, second, millisecond, and precision. Omitted time fields default to 0. When no to is supplied, the resolved precision determines the complete span.

`from.year` number

Full year value. Supports BCE dates as negative numbers.

`from.month` number

Include for month-level precision. Defaults to January.

`from.day` number

Include for day-level precision. Defaults to the first of the month.

`from.hour / minute / second / millisecond` number new

Optional timezone-free time components. Valid ranges are hour 0–23, minute and second 0–59, and millisecond 0–999; omitted fields default to 0.

`from.precision` PrecisionString new

Determines the normalized start boundary, and the whole band span when to is omitted. If omitted, precision is inferred from the finest supplied time component, including a value of 0. With no time components it defaults to 'day'. Supported strings: 'millisecond', 'second', 'minute', 'hour', 'day', 'month', 'year', 'decade', 'century', 'millennium', 'million-years', 'billion-years'.

Precision is the source of truth: finer fields are ignored. For example, { year: 1840, month: 6, precision: 'year' } resolves to the full year 1840.

deprecated Legacy numeric precision values remain supported for compatibility; use the descriptive strings or the PRECISION_* constants, which now resolve to those strings.

`to` DateInput

End of the band. It accepts the same calendar and time fields as from; omitted time fields default to 0. Omit it to use the resolved from precision for the whole span. It is ignored when isToPresent is true.

`to.year` number

Year the band ends. Supports BCE values as negative numbers.

Required when to is provided.

`to.month` number

Optional month component. Defaults to January.

`to.day` number

Optional day component. Defaults to the first of the month.

`to.hour / minute / second / millisecond` number new

Optional timezone-free time components with the same ranges and defaults as from.

`to.precision` PrecisionString

Same supported strings and inference rules as from.precision. When to is supplied, its precision is resolved independently from from.precision and determines the normalized inclusive end boundary.

`isToPresent` boolean

Extend the band to the current date. Mutually exclusive with to.

`style` TimeBandStyle

Sparse overrides merged with timeBand.defaultStyle. See Time Band Style.

`visibility` 'visible' | 'hidden' | function

Defaults to 'visible'. Set 'hidden' or return a value from a function receiving the TimeBand instance to toggle dynamically.

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 new

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 */ ]
};

`visible` boolean

Draw Time Bands when true. Toggle this to hide bands without unloading them.

`reserveSpace` boolean

When true, increases the effective vertical offset only while Time Bands are visible and at least one band is loaded. This moves the main line and dependent layout upward to leave room below it.

`reserveSpacePixels` number

Extra pixels added to the effective vertical offset when reserveSpace is true, Time Bands are visible, and at least one band is loaded.

`area` object

Vertical extent of the rendered Time Bands above and below the main line. Each side accepts pixel counts, 'edge' to stretch to the canvas edge, or an object of the form { value: 'edge', padding: <px> } to stretch to the edge with padding.

`defaultStyle` object

Base styles applied to every band. See Time Band Style for a breakdown of each field.

`data` TimeBandData[]

Array of band objects loaded at start-up. Each entry follows the Time Band Schema.

Time Band Style new

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
  }
};

`backgroundColor` string

Fill color for each band. Use RGBA for translucent overlays.

`border` object

Outline applied to the band area. Set width to 0 to remove it.

`border.color` string

Border color in any CSS-compatible format.

`border.width` number

Border thickness in pixels.

`text` object

Typography and placement for band labels. Applies when a band has a title.

`text.font` string

Canvas font declaration (font-style, size, family).

`text.color` string

Label text color.

`text.align` string

Horizontal alignment within the band (left, center, or right).

`text.baseline` string

Canvas baseline used for vertical placement. Defaults to bottom.

`text.verticalAlign` 'top' | 'middle' | 'bottom'

Anchors text to the top edge, vertical middle, or bottom edge of the band. The default is 'bottom'.

`text.margin` number

Inset in pixels from the aligned edge.

`text.offsetY` number

Fine-tune vertical placement relative to the baseline.

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 new

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?)

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?)

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');

Time Band Documentation

Time Band Schema new

Time Band Options new

Time Band Style new

Time Band Methods new

.setOption(option, value?)

Parameters

Returns

.setStyle(option, value?)

Parameters

Returns

Need More Help?