Chartjs.FFI

data ChartInstance

Opaque handle to a Chart.js instance.

createChart :: HTMLElement -> Json -> Effect ChartInstance

Create a new Chart.js instance on a canvas element with a JSON config.

updateChart :: ChartInstance -> Json -> Maybe String -> Effect Unit

Update an existing chart with a new JSON config. The mode parameter controls animation: Nothing for default animation, Just "none" to skip animation, or any other Chart.js update mode.

destroyChart :: ChartInstance -> Effect Unit

Destroy a chart instance and release its resources.

createChartWithCallbacks :: HTMLElement -> Json -> Foreign -> Effect ChartInstance

Create a chart with a JSON config and a callbacks/overlays object.

updateChartWithCallbacks :: ChartInstance -> Json -> Foreign -> Maybe String -> Effect Unit

Update a chart with a new JSON config and a callbacks/overlays object. The mode parameter controls animation: Nothing for default animation, Just "none" to skip animation, or any other Chart.js update mode.

stopChart :: ChartInstance -> Effect ChartInstance

Stop the current animation. Returns the chart instance for chaining.

toBase64Image :: ChartInstance -> Maybe String -> Maybe Number -> Effect String

Export the chart as a base64-encoded image data URL. The type parameter is a MIME type (e.g. "image/png", "image/jpeg"). The quality parameter is 0-1 for lossy formats like JPEG.

setDatasetVisibility :: ChartInstance -> Int -> Boolean -> Effect Unit

Set the visibility of a dataset. Call updateChart afterward to render.

isDatasetVisible :: ChartInstance -> Int -> Effect Boolean

Check whether a dataset is currently visible.

hideDataset :: ChartInstance -> Int -> Maybe Int -> Effect Unit

Hide a dataset or a specific data element with animation. Pass Nothing for dataIndex to hide the entire dataset.

showDataset :: ChartInstance -> Int -> Maybe Int -> Effect Unit

Show a dataset or a specific data element with animation. Pass Nothing for dataIndex to show the entire dataset.

renderChart :: ChartInstance -> Effect Unit

Trigger a redraw of existing chart elements. Does NOT update elements for new data — use updateChart when data changes.

resetChart :: ChartInstance -> Effect Unit

Restore the chart to its initial state before animations began. A subsequent updateChart call will trigger new animations.

resizeChart :: ChartInstance -> Maybe Number -> Maybe Number -> Effect Unit

Adjust canvas dimensions. Pass Nothing for both width and height to resize to match the container. Normally called automatically when the container resizes; call this explicitly if you changed the container size imperatively.

clearChart :: ChartInstance -> Effect ChartInstance

Clear the chart canvas. Used internally between animation frames; rarely needed directly. Returns the chart instance for chaining.

getDatasetMeta :: ChartInstance -> Int -> Effect Foreign

Look up the internal metadata object for a dataset by index. The returned Foreign is Chart.js's ChartMeta — a mutable bag of controller/scale/data references. Consumers who need specific fields (e.g. data, visible, hidden) coerce via Foreign operations.

getElementsAtEventForMode :: ChartInstance -> Event -> InteractionMode -> InteractionOptions -> Boolean -> Effect (Array InteractionItem)

Find chart elements matching an event for a given interaction mode. Useful for click handlers that need to know which point/bar/arc was hit. The useFinalPosition flag controls whether to use the animation's final position (true) or current position (false).

interactionOptionsToForeign :: InteractionOptions -> Foreign

Convert InteractionOptions to a plain JS object suitable for passing to Chart.js's getElementsAtEventForMode. Nothing fields are dropped so Chart.js uses its defaults for them. Exported for testing — callers normally use getElementsAtEventForMode directly.

toggleDataVisibility :: ChartInstance -> Int -> Effect Unit

Toggle the visibility of a single data element by its index within the dataset. Inverts the current visibility flag on the matching meta entry. Call updateChart afterwards to render the change.

getDataVisibility :: ChartInstance -> Int -> Effect Boolean

Check whether a single data element is currently visible.

getActiveElements :: ChartInstance -> Effect (Array Foreign)

Get the array of currently active (hovered or otherwise highlighted) chart elements. Each entry is an opaque Foreign wrapping Chart.js's ActiveElement (which has datasetIndex, index, and element).

setActiveElements :: ChartInstance -> Array { datasetIndex :: Int, index :: Int } -> Effect Unit

Programmatically set the active elements (e.g. to highlight a data point from outside a hover handler). Each entry must specify a datasetIndex and index. Call updateChart to apply.

isPluginEnabled :: ChartInstance -> String -> Effect Boolean

Check whether a Chart.js plugin is currently enabled by its plugin id (the string returned by the plugin's id field). Useful for conditional behavior in custom plugins.

getSortedVisibleDatasetMetas :: ChartInstance -> Effect (Array Foreign)

Get the sorted list of visible dataset metadata objects. Each entry is the same opaque Foreign shape returned by getDatasetMeta, filtered to only the visible datasets and sorted in draw order.

getVisibleDatasetCount :: ChartInstance -> Effect Int

Return the number of currently visible datasets.

chartRegister :: Array Foreign -> Effect Unit

Register one or more Chart.js components (controllers, plugins, scales, or elements) globally. Each item must be a JS object the Chart.js registry recognizes — typically a controller class with an id field. After registration, the component is available to all subsequent chart instances in this process. Pair with CustomType from Chartjs.Types (#27) to use a registered controller as a chart type.

The PS argument is Array Foreign because Chart.js components are arbitrary JS objects (and registering plugins / controllers / scales / elements works the same way at the API level). Build the components in JS or via unsafeToForeign from PS.

chartUnregister :: Array Foreign -> Effect Unit

Reverse chartRegister. Removes the given components from the global registry. Mostly useful for tests; production code rarely needs to unregister.

getChartByElement :: HTMLElement -> Effect (Maybe ChartInstance)

Look up an existing chart instance by its canvas element. Returns Nothing if no chart is currently bound to the canvas. Useful for accessing a chart from outside the code that created it (e.g. from a separate event handler that has only the DOM reference).

getChartByCanvasId :: String -> Effect (Maybe ChartInstance)

Look up an existing chart instance by canvas element id (the id attribute of the underlying <canvas>). Returns Nothing if no matching canvas exists or no chart is bound to it.

chartRegistry :: Effect Foreign

Get the global Chart.js registry as an opaque Foreign value. The registry exposes typed sub-registries (controllers, plugins, scales, elements) plus generic add / remove methods. Use this for advanced registration scenarios — registering a custom interaction mode (via Chart.helpers.registry) or a custom tooltip positioner, both of which the typed PureScript API does not yet model. Consumers using this should reference Chart.js's registry API docs directly.

isPointInArea :: ChartInstance -> { x :: Number, y :: Number } -> Effect Boolean

Check whether a pixel coordinate falls inside the chart area (the plotting rectangle, excluding axes/legends/padding). Useful for custom event handlers that need to distinguish clicks inside the chart from clicks on surrounding chrome.

getChartContext :: ChartInstance -> Effect Foreign

Return the chart's context object — { chart, type }. The chart field is the Chart.js instance itself; type is a string like "chart". Primarily used inside custom plugins that need to pass context down. Returned as Foreign because the shape is self-referential.

notifyPlugins :: ChartInstance -> String -> Foreign -> Effect Boolean

Notify all registered plugins of a lifecycle hook. hook is the event name (e.g. "beforeDraw", "afterUpdate"). args is an arbitrary JS object passed to each plugin's handler — build via unsafeToForeign. Returns false if any plugin returned false to cancel the hook, true otherwise. Rarely needed outside custom plugin authoring.