Skip to main content

Graph

A single chart bound to a container frame. Renders line and bar series with animated entries, gradient infill, optional smoothing, hover tooltips, and a legend, and re-renders automatically when the data, configuration, or container size changes. Renders are deferred and coalesced, so several mutations in one frame produce a single redraw.

Create one with Plottr.new.

Functions​

new​

</>
Graph.new(
container: GuiObject,--

Any GuiObject; the canvas fills it

config: PartialConfig?--

Options merged over the defaults

) → Graph

Creates a new graph that renders into the given container. The graph fills the container and starts empty; add data with Graph:setSeries.

setSeries​

</>
Graph:setSeries(series: {Series}) → ()

Replaces all series and re-renders with the entry animation. The series and their value arrays are copied, so the graph never mutates what you pass in.

Errors

TypeDescription
duplicate series nameThrown when two series share a name

addSeries​

</>
Graph:addSeries(series: Series) → ()

Appends one series and re-renders with the entry animation.

Errors

TypeDescription
duplicate series nameThrown when a series with that name exists

removeSeries​

</>
Graph:removeSeries(name: string) → boolean--

Whether a series with that name existed

Removes the series with the given name.

updateSeries​

</>
Graph:updateSeries(
name: string,
values: {number}
) → boolean--

Whether a series with that name existed

Replaces the values of one series and redraws instantly, without replaying the entry animation.

getSeries​

</>
Graph:getSeries(name: string) → Series?

Returns a copy of the named series, or nil when there is no such series. The copy is detached: mutating it does not affect the graph.

getSeriesNames​

</>
Graph:getSeriesNames() → {string}

Returns every series name, in render order.

setSeriesVisible​

</>
Graph:setSeriesVisible(
name: string,
visible: boolean
) → boolean--

Whether a series with that name existed

Shows or hides one series without removing its data. Hidden series are left out of the axis range and dimmed in the legend.

clear​

</>
Graph:clear() → ()

Removes every series, leaving an empty plot.

push​

</>
Graph:push(
seriesName: string,
value: number
) → ()

Appends a value to the named series and redraws instantly, without replaying the entry animation — intended for realtime/streaming data. When Config.maxPoints is set, older values scroll off the front. Multiple pushes in one frame coalesce into a single redraw.

Errors

TypeDescription
unknown seriesThrown when no series has the given name

configure​

</>
Graph:configure(config: PartialConfig) → ()

Merges the given options into the current configuration and re-renders. Set an optional field to Plottr.None to clear it back to nil.

setTheme​

</>
Graph:setTheme(theme: Theme) → ()

Swaps the theme and re-renders.

onPointClicked​

</>
Graph:onPointClicked(handler: (event: PointEvent) → ()) → () → ()

Registers a handler for clicks on a data point or bar. Returns a function that unregisters it. 

local disconnect = graph:onPointClicked(function(event)
	print(event.seriesName, event.index, event.value)
end)

render​

</>
Graph:render() → ()

Forces an immediate animated re-render, cancelling any redraw that was already queued for this frame.

destroy​

</>
Graph:destroy() → ()

Destroys the graph and every instance it created. Safe to call twice.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new graph that renders into the given container. The graph\nfills the container and starts empty; add data with [Graph:setSeries].",
            "params": [
                {
                    "name": "container",
                    "desc": "Any GuiObject; the canvas fills it",
                    "lua_type": "GuiObject"
                },
                {
                    "name": "config",
                    "desc": "Options merged over the defaults",
                    "lua_type": "PartialConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Graph"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 256,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "setSeries",
            "desc": "Replaces all series and re-renders with the entry animation. The series\nand their value arrays are copied, so the graph never mutates what you\npass in.",
            "params": [
                {
                    "name": "series",
                    "desc": "",
                    "lua_type": "{ Series }"
                }
            ],
            "returns": [],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "duplicate series name",
                    "desc": "Thrown when two series share a name"
                }
            ],
            "source": {
                "line": 320,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "addSeries",
            "desc": "Appends one series and re-renders with the entry animation.",
            "params": [
                {
                    "name": "series",
                    "desc": "",
                    "lua_type": "Series"
                }
            ],
            "returns": [],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "duplicate series name",
                    "desc": "Thrown when a series with that name exists"
                }
            ],
            "source": {
                "line": 341,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "removeSeries",
            "desc": "Removes the series with the given name.",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "Whether a series with that name existed",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 358,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "updateSeries",
            "desc": "Replaces the values of one series and redraws instantly, without\nreplaying the entry animation.",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "values",
                    "desc": "",
                    "lua_type": "{ number }"
                }
            ],
            "returns": [
                {
                    "desc": "Whether a series with that name existed",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 380,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "getSeries",
            "desc": "Returns a copy of the named series, or nil when there is no such series.\nThe copy is detached: mutating it does not affect the graph.",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Series?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 403,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "getSeriesNames",
            "desc": "Returns every series name, in render order.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ string }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 415,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "setSeriesVisible",
            "desc": "Shows or hides one series without removing its data. Hidden series are\nleft out of the axis range and dimmed in the legend.",
            "params": [
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "visible",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [
                {
                    "desc": "Whether a series with that name existed",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 433,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "clear",
            "desc": "Removes every series, leaving an empty plot.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 453,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "push",
            "desc": "Appends a value to the named series and redraws instantly, without\nreplaying the entry animation — intended for realtime/streaming data.\nWhen [Config].maxPoints is set, older values scroll off the front.\nMultiple pushes in one frame coalesce into a single redraw.",
            "params": [
                {
                    "name": "seriesName",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "unknown series",
                    "desc": "Thrown when no series has the given name"
                }
            ],
            "source": {
                "line": 471,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "configure",
            "desc": "Merges the given options into the current configuration and re-renders.\nSet an optional field to [Plottr.None] to clear it back to nil.",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "PartialConfig"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 505,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "setTheme",
            "desc": "Swaps the theme and re-renders.",
            "params": [
                {
                    "name": "theme",
                    "desc": "",
                    "lua_type": "Theme"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 519,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "onPointClicked",
            "desc": "Registers a handler for clicks on a data point or bar. Returns a function\nthat unregisters it.\n\n```lua\nlocal disconnect = graph:onPointClicked(function(event)\n\tprint(event.seriesName, event.index, event.value)\nend)\n```",
            "params": [
                {
                    "name": "handler",
                    "desc": "",
                    "lua_type": "(event: PointEvent) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 538,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "render",
            "desc": "Forces an immediate animated re-render, cancelling any redraw that was\nalready queued for this frame.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 557,
                "path": "src/Graph.luau"
            }
        },
        {
            "name": "destroy",
            "desc": "Destroys the graph and every instance it created. Safe to call twice.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 571,
                "path": "src/Graph.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "Graph",
    "desc": "A single chart bound to a container frame. Renders line and bar series\nwith animated entries, gradient infill, optional smoothing, hover\ntooltips, and a legend, and re-renders automatically when the data,\nconfiguration, or container size changes. Renders are deferred and\ncoalesced, so several mutations in one frame produce a single redraw.\n\nCreate one with [Plottr.new].",
    "source": {
        "line": 32,
        "path": "src/Graph.luau"
    }
}