PyGWalker Component API

Use pygwalker.component(...) when you want to build PyGWalker charts with Python method chains instead of only using the drag-and-drop explorer.

import pygwalker as pyg
 
chart = (
    pyg.component(df, spec_path="./gw_config.json", computation="browser")
    .bar()
    .encode(x="category", y="sum(revenue)", color="region")
    .layout(width=720, height=420)
)
 
html = chart.to_html()

Factory

pyg.component(
    dataset,
    *,
    field_specs=None,
    spec="",
    spec_path=None,
    spec_io_mode="rw",
    theme_key="vega",
    appearance="media",
    show_cloud_tool=False,
    computation=None,
    kernel_computation=None,
    kanaries_api_key="",
    **kwargs,
) -> Component

dataset can be a pandas DataFrame, polars DataFrame, pyarrow Table, database Connector, or connector-style string.

Use spec_path for a local chart-state file. Use computation for new code; kernel_computation is legacy and scheduled for removal in PyGWalker 0.7.0.

Mark methods

Mark methods return a copied Component, so chains are safe to reuse.

Method	Chart mark
`.bar()`	Bar
`.line()`	Line
`.area()`	Area
`.trail()`	Trail
`.scatter()`	Point/scatter
`.circle()`	Circle
`.tick()`	Tick
`.rect()`	Rect
`.arc()`	Arc
`.text()`	Text
`.box()`	Box plot
`.table()`	Table
`.poi()`	Geographic point of interest

Encodings

Use .encode(...) to map fields to visual channels.

chart = (
    pyg.component(df)
    .scatter()
    .encode(
        x="ad_spend",
        y="revenue",
        color="channel",
        size="sum(orders)",
    )
)

Supported channels:

encode(
    x="",
    y="",
    color="",
    opacity="",
    size="",
    shape="",
    radius="",
    theta="",
    longitude="",
    latitude="",
    geoid="",
    details="",
    text="",
)

x and y can also receive a list of fields. Aggregate expressions such as sum(revenue) use the Graphic Walker aggregation model.

Layout and modes

Set chart size and layout options with .layout(...).

chart = chart.layout(mode="fixed", width=640, height=360)

Switch render modes with:

Method	Use
`.profiling()`	Render the profiling/table mode.
`.explorer()`	Render the full explorer around the current chart state.
`.copy()`	Create an explicit copy before branching a chart chain.
`.to_html()`	Return HTML for the current component.

Static export limits

Component .to_html() is static HTML. Explorer and profiling component exports reject live kernel/cloud computation:

# Use browser computation when exporting component HTML.
component = pyg.component(df, computation="browser")
html = component.explorer().to_html()

Use a live adapter such as Notebook APIs, Streamlit, or Gradio when the chart needs kernel or cloud computation.