Interface: Race
The chart API object returned by race.
Exposes methods to control the racing bar chart programmatically — play/pause, navigate dates, select bars, filter groups, listen to events, and more.
See
https://racing-bars.hatemhosny.dev/documentation/api
Example
const racer = await race('/data/population.csv', '#race', { dataType: 'csv' });
racer.pause();
console.log(racer.getDate());
racer.on('dateChange', ({ date }) => console.log('date change', date));
racer.destroy();
Properties
changeOptions()
changeOptions: (
newOptions) =>Promise<void>
Changes chart options during runtime.
Note: dataShape and dataType cannot be changed and will throw an error.
Parameters
• newOptions: Partial<Options>
A partial Options object with the options to update.
Returns
Promise<void>
Throws
If dataShape or dataType are included.
Defined in
dec()
dec: (
value) =>void
Moves the chart backward by the specified number of dates.
Parameters
• value: number
Number of dates to go back (default: 1).
Returns
void
Defined in
destroy()
destroy: () =>
void
Destroys the chart instance and cleans up all resources. After calling this, subsequent API calls will throw an error.
Returns
void
Defined in
getAllDates()
getAllDates: () =>
string[]
Returns an array of all unique dates in the dataset, sorted ascending.
Returns
string[]
Defined in
getDate()
getDate: () =>
string
Returns the current date as a 'YYYY-MM-DD' string.
Returns
string
Defined in
hideGroup()
hideGroup: (
group) =>void
Hides all bars belonging to the specified group.
Parameters
• group: string
The group name to hide.
Returns
void
Defined in
inc()
inc: (
value) =>void
Advances the chart forward by the specified number of dates.
Parameters
• value: number
Number of dates to advance (default: 1).
Returns
void
Defined in
isRunning()
isRunning: () =>
boolean
Returns true if the chart is animating, false otherwise.
Returns
boolean
Defined in
on()
on: (
event,fn) =>void
Registers a callback for chart lifecycle events.
Parameters
• event: EventType
The event type: 'dateChange', 'firstDate', 'lastDate', 'play', or 'pause'.
• fn: ApiCallback
Callback function receiving a TickDetails object.
Returns
void
An object with a remove() method to unsubscribe.
Defined in
onDate()
onDate: (
date,fn) =>void
Registers a callback that fires when a specific date becomes the current date.
Parameters
• date: string | Date
The date to watch (string or Date object).
• fn: ApiCallback
Callback function receiving a TickDetails object.
Returns
void
An object with a remove() method to unsubscribe.
Defined in
pause()
pause: () =>
void
Pauses the chart at the current date.
Returns
void
Defined in
play()
play: () =>
void
Starts running the chart animation. No-op if already running.
Returns
void
Defined in
select()
select: (
name) =>void
Selects a bar by name, adding the CSS class selected to it.
Parameters
• name: string
The name of the bar to select.
Returns
void
Defined in
setDate()
setDate: (
inputDate) =>void
Sets the chart to a specific date.
Parameters
• inputDate: string | Date
A date string (e.g. '1960-01-01') or a JavaScript Date object.
Returns
void
Defined in
showAllGroups()
showAllGroups: () =>
void
Shows all groups (resets any group filters).
Returns
void
Defined in
showGroup()
showGroup: (
group) =>void
Shows bars of the specified group if they were previously hidden.
Parameters
• group: string
The group name to show.
Returns
void
Defined in
showOnlyGroup()
showOnlyGroup: (
group) =>void
Hides all groups except the one specified.
Parameters
• group: string
The group name to keep visible.
Returns
void
Defined in
skipBack()
skipBack: () =>
void
Stops the chart and resets the date to the first date in the dataset.
Returns
void
Defined in
skipForward()
skipForward: () =>
void
Stops the chart and sets the date to the last date in the dataset.
Returns
void
Defined in
toggle()
toggle: () =>
void
Toggles between play and pause states.
Returns
void
Defined in
unselect()
unselect: (
name) =>void
Unselects a previously selected bar by name.
Parameters
• name: string
The name of the bar to unselect.
Returns
void
Defined in
unselectAll()
unselectAll: () =>
void
Unselects all bars.
Returns
void