Skip to content

colight.core

Interactivity

State

Initializes state variables in the Plot widget.

Parameters

  • values (dict[str, Any]): A dictionary mapping state variable names to their initial values.

  • sync (Union[set[str], bool, None]): Controls which state variables are synced between Python and JavaScript.

    If True, all variables are synced. If a set, only variables in the set are synced.

    If None or False, no variables are synced. Defaults to None.

Returns

  • An object that initializes the state variables when rendered. (Marker)

Examples: 

Plot.State({"count": 0, "name": "foo"})  # Initialize without sync
Plot.State({"count": 0}, sync=True)  # Sync all variables
Plot.State({"x": 0, "y": 1}, sync={"x"})  # Only sync "x"

onChange

Adds callbacks to be invoked when state changes.

Parameters

  • callbacks (dict): A dictionary mapping state keys to callbacks, which are called with (widget, event) when the corresponding state changes.

Returns

  • A Listener object that will be rendered to set up the event handlers.

Frames

Create an animated plot that cycles through a list of frames.

Parameters

  • frames (list): A list of plot specifications or renderable objects to animate.

  • key (str | None): The state key to use for the frame index. If None, uses "frame".

  • slider (bool): Whether to show the slider control. Defaults to True.

  • tail (bool): Whether animation should stop at the end. Defaults to False.

  • **opts (Any): Additional options for the animation, such as fps (frames per second).

Returns

  • A Hiccup-style representation of the animated plot. (LayoutItem)

Slider

channel

Declare a prop whose value is resampled client-side from shipped samples.

The values rows travel once, as one array. A $state scalar named parameter indexes them: whenever it changes, the browser resamples row at[i]..at[i+1] under rule and hands the result to the prop, with no Python round trip. The declaration is legible to colight inspect, which reports the parameter, its domain, the rule and the prop it drives.

A channel carries no notion of time: parameter="t" is a clock, parameter="grade" a cutoff, parameter="blend" a morph.

Parameters

  • parameter (str): The $state key this channel is indexed by.

  • values (Any): Array-like of shape (N, ...) — row i is the value at at[i].

    Scalars per row (N,), vectors (N, 3)/(N, 4), and wide rows (N, M)

    (e.g. a table of flattened vertex positions) are all accepted.

  • at (Optional[Sequence[float]]): (N,) strictly increasing sample coordinates. Defaults to

    arange(N).

  • rule (str): How values between samples are produced — "nearest", "step"

    (hold the lower sample), "linear" (elementwise lerp) or

    "qlerp" (normalized quaternion lerp with antipodal correction,

    for (N, 4) xyzw rows).

Returns

  • A JSCall to the client-side resampler, usable anywhere a prop value (JSCall)

  • is accepted. (JSCall)

Raises

  • ValueError: On an unknown rule, a malformed parameter name, an empty or mismatched at, non-increasing at, or qlerp on values that are not (N, 4).

Layout

Useful for layouts and custom views.

Note that syntax sugar exists for Column (|) and Row (&) using operator overloading.

(A & B) | C # A & B on one row, with C below.

Column

Render children in a column.

Parameters

  • *items (Any): Items to render in the column

  • **kwargs: Additional options including:

    heights: List of flex sizes for each child. Can be:

    - Numbers for flex ratios (e.g. [1, 2] means second item is twice as tall)

- Strings with fractions (e.g. ["1/2", "1/2"] for equal halves)

- Strings with explicit sizes (e.g. ["100px", "200px"])

    gap: Gap size between items (default: 1)

    className: Additional CSS classes

Grid

Creates a responsive grid layout that automatically arranges child elements in a grid pattern.

The grid adjusts the number of columns based on the available width and minimum width per item. Each item maintains consistent spacing controlled by gap parameters.

Parameters

  • *children: Child elements to arrange in the grid.

  • **opts: Grid options including:

    • minWidth (int): Minimum width for each grid item in pixels. Default is 165.

    • gap (int): Gap size for both row and column gaps. Default is 1.

    • rowGap (int): Vertical gap between rows. Overrides gap if specified.

    • colGap (int): Horizontal gap between columns. Overrides gap if specified.

    • cols (int): Fixed number of columns. If not set, columns are calculated based on minWidth.

    • minCols (int): Minimum number of columns. Default is 1.

    • maxCols (int): Maximum number of columns.

    • widths (List[Union[int, str]]): Array of column widths. Can be numbers (for fractions) or strings.

    • heights (List[Union[int, str]]): Array of row heights. Can be numbers (for fractions) or strings.

    • height (str): Container height.

    • style (dict): Additional CSS styles to apply to grid container.

    • className (str): Additional CSS classes to apply.

Returns

  • A grid layout component that will be rendered in the JavaScript runtime.

Row

Render children in a row.

Parameters

  • *items (Any): Items to render in the row

  • **kwargs: Additional options including:

    widths: List of flex sizes for each child. Can be:

    - Numbers for flex ratios (e.g. [1, 2] means second item is twice as wide)

- Strings with fractions (e.g. ["1/2", "1/2"] for equal halves)

- Strings with explicit sizes (e.g. ["100px", "200px"])

    gap: Gap size between items (default: 1)

    className: Additional CSS classes

Flow Control

cond

Render content based on conditions, like Clojure's cond.

Takes pairs of test/expression arguments, evaluating each test in order. When a test is truthy, returns its corresponding expression. An optional final argument serves as the "else" expression.

Parameters

  • *args: Alternating test/expression pairs, with optional final else expression

case

Render content based on matching a value against cases, like a switch statement.

Takes a value to match against, followed by pairs of case/expression arguments. When a case matches the value, returns its corresponding expression. An optional final argument serves as the default expression.

Parameters

  • value (Union[JSCode, str, Any]): The value to match against cases

  • *args: Alternating case/expression pairs, with optional final default expression

JavaScript Interop

Import

Import JavaScript code into the Colight environment.

Parameters

  • source (str): JavaScript source code. Can be:

    • Inline JavaScript code

    • URL starting with http(s):// for remote modules

    • Local file path starting with path: prefix

  • alias (Optional[str]): Namespace alias for the entire module

  • default (Optional[str]): Name for the default export

  • refer (Optional[list[str]]): Set of names to import directly, or True to import all

  • refer_all (bool): Alternative to refer=True

  • rename (Optional[dict[str, str]]): Dict of original->new names for referred imports

  • exclude (Optional[list[str]]): Set of names to exclude when using refer_all

  • format (str): Module format ('esm' or 'commonjs')

Imported JavaScript code can access: - colight.imports: Previous imports in the current plot (only for CommonJS imports) - React, d3, html (for hiccup) and colight.api are defined globally

Examples: 

# CDN import with namespace alias
Plot.Import(
    source="https://cdn.skypack.dev/lodash-es",
    alias="_",
    refer=["flattenDeep", "partition"],
    rename={"flattenDeep": "deepFlatten"}
)

# Local file import
Plot.Import(
    source="path:src/app/utils.js",  # relative to working directory
    refer=["formatDate"]
)

# Inline source with refer_all
Plot.Import(
    source='''
    export const add = (a, b) => a + b;
    export const subtract = (a, b) => a - b;
    ''',
    refer_all=True,
    exclude=["subtract"]
)

# Default export handling
Plot.Import(
    source="https://cdn.skypack.dev/d3-scale",
    default="createScale"
)

js

Represents raw JavaScript code to be evaluated as a LayoutItem.

The code will be evaluated in a scope that includes: - $state: Current plot state - html: render HTML using a JavaScript hiccup syntax - d3: D3.js library - colight.api: roughly, the api exposed via the colight.plot module - Any additional variables passed as kwargs

Parameters

  • txt (str): JavaScript code with optional %1, %2, etc. placeholders

  • *params (Any): Values to substitute for %1, %2, etc. placeholders

  • expression (bool): Whether to evaluate as expression or statement

  • **kwargs (Any): Additional variables to include in the JavaScript scope

Formatting

html

md

Render a string as Markdown, in a LayoutItem.

katex

Render a TeX string, in a LayoutItem.