HistropediaJS Time Band Documentation

Time Band Schema new

Time bands describe the spans rendered behind the main timeline line. They use the same day/month/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 */,
    precision: /* optional: 'day' | 'month' | 'year' | 'decade' | 'century' | 'millennium' | 'million-years' | 'billion-years'; default: 'day' */
  },

  to: { /* optional */
    year: /* required: number */,
    month: /* optional: 1-12 */,
    day: /* optional: 1-31 */,
    precision: /* optional: same precision strings; default: 'day' */
  },
  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, and precision. When no to is supplied, the precision determines the time span represented by the band.

`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.precision` PrecisionString new

Determines the normalized start boundary, and the whole band span when to is omitted. Supported strings: '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. Mirror the from shape when provided, or omit to use the from.precision to determine the span. 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.precision` PrecisionString

Same supported strings as from.precision. When to is supplied, to.precision determines the normalized inclusive end boundary independently from from.precision.

`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.

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

Reserve extra vertical room below the main line when bands are visible. Prevents existing layouts from shifting upward.

`reserveSpacePixels` number

Pixel height reserved below the main line whenever reserveSpace is active.

`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` string

Anchors text to the top or bottom edge of the band.

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