Nib integrates with Swift Charts to provide native, GPU-accelerated data visualizations. You define charts using a declarative API: provide your data as a list of dictionaries, and specify mark types that map data fields to visual properties.

Creating a chart¶

import nib

chart = nib.Chart(
    data=[
        {"month": "Jan", "sales": 100},
        {"month": "Feb", "sales": 150},
        {"month": "Mar", "sales": 200},
        {"month": "Apr", "sales": 175},
        {"month": "May", "sales": 250},
    ],
    marks=[nib.LineMark(x="month", y="sales")],
    width=350,
    height=220,
)

The Chart constructor takes:

Standard view modifiers (width, height, padding, corner_radius, etc.) are also supported.

Data format¶

Data is a list of dictionaries where each dictionary represents a row. The keys correspond to the field names used in your marks:

data = [
    {"month": "Jan", "revenue": 4200, "expenses": 3100},
    {"month": "Feb", "revenue": 5100, "expenses": 3400},
    {"month": "Mar", "revenue": 4800, "expenses": 3200},
]

Mark types¶

LineMark¶

Connects data points with a continuous line. Best for trends over time:

nib.LineMark(x="month", y="sales")

BarMark¶

Displays data as rectangular bars. Best for comparing categories:

nib.BarMark(x="category", y="value")

AreaMark¶

Fills the region between a line and a baseline:

nib.AreaMark(x="date", y="revenue", foreground_style="#3B82F6", opacity=0.3)

PointMark¶

Displays individual data points as symbols. Best for scatter plots:

nib.PointMark(x="height", y="weight", foreground_style="#EF4444")

SectorMark¶

Creates pie and donut charts:

nib.SectorMark(
    angle="value",
    foreground_style=nib.PlottableField("category"),
)

RuleMark¶

Draws a reference line (horizontal or vertical):

# Horizontal line at y=100
nib.RuleMark(y=100, foreground_style="#EF4444", line_width=2)

# Vertical line at x position
nib.RuleMark(x="2024-06-15", foreground_style="#6366F1")

RectMark¶

Draws filled rectangles for heatmaps and range charts:

nib.RectMark(
    x="weekday", y="hour",
    foreground_style=nib.PlottableField("intensity"),
    corner_radius=2,
)

PlottableField¶

Use PlottableField to reference data columns with optional type hints:

from nib import PlottableField

# Simple field reference (equivalent to just passing "month")
nib.LineMark(x=PlottableField("month"), y=PlottableField("sales"))

# With type hint for proper scale selection
nib.LineMark(
    x=PlottableField("date", type="temporal"),
    y=PlottableField("temperature", type="quantitative"),
)

Available types: "quantitative" (numeric), "nominal" (categorical), "temporal" (dates/times).

Multiple series¶

To display multiple data series with automatic color assignment, pass a PlottableField as foreground_style:

data = [
    {"month": "Jan", "value": 100, "series": "Revenue"},
    {"month": "Jan", "value": 80, "series": "Expenses"},
    {"month": "Feb", "value": 150, "series": "Revenue"},
    {"month": "Feb", "value": 90, "series": "Expenses"},
    {"month": "Mar", "value": 200, "series": "Revenue"},
    {"month": "Mar", "value": 110, "series": "Expenses"},
]

chart = nib.Chart(
    data=data,
    marks=[
        nib.LineMark(
            x="month",
            y="value",
            foreground_style=nib.PlottableField("series"),
        ),
    ],
    width=350,
    height=220,
)

Swift Charts automatically assigns distinct colors to each unique value in the series field.

Combining marks¶

Combine multiple mark types in a single chart for layered visualizations:

chart = nib.Chart(
    data=data,
    marks=[
        nib.AreaMark(x="month", y="sales", foreground_style="#3B82F6", opacity=0.2),
        nib.LineMark(x="month", y="sales", foreground_style="#3B82F6"),
        nib.PointMark(x="month", y="sales", foreground_style="#3B82F6"),
        nib.RuleMark(y=150, foreground_style="#EF4444", line_width=1),
    ],
    width=350,
    height=220,
)

This creates an area chart with a line overlay, point markers at each data point, and a horizontal reference line at y=150.

Axis configuration¶

Use ChartAxis to customize axis appearance:

chart = nib.Chart(
    data=data,
    marks=[nib.BarMark(x="month", y="revenue")],
    x_axis=nib.ChartAxis(
        label="Month",
        position="bottom",
    ),
    y_axis=nib.ChartAxis(
        label="Revenue ($)",
        grid_lines=True,
        format="currency",
        grid_color="#333333",
        label_color="#666666",
    ),
)

Legend configuration¶

Control the chart legend with ChartLegend:

chart = nib.Chart(
    data=data,
    marks=[nib.LineMark(x="month", y="value", foreground_style=nib.PlottableField("series"))],
    legend=nib.ChartLegend(
        position="bottom",
        title="Category",
    ),
)

# Or hide the legend entirely
chart = nib.Chart(
    data=data,
    marks=[...],
    legend=False,
)

InterpolationMethod¶

Control how lines and areas are drawn between data points:

nib.LineMark(
    x="month", y="sales",
    interpolation=nib.InterpolationMethod.MONOTONE,
)

StackingMethod¶

Control how overlapping bars or areas are stacked:

nib.BarMark(
    x="month", y="sales",
    foreground_style=nib.PlottableField("region"),
    stacking=nib.StackingMethod.STANDARD,
)

SymbolShape¶

Marker shapes for PointMark and LineMark:

nib.PointMark(x="x", y="y", symbol=nib.SymbolShape.DIAMOND)

Available shapes: CIRCLE, SQUARE, TRIANGLE, DIAMOND, CROSS, PLUS, PENTAGON, HEXAGON.

Reactive data updates¶

Chart data is reactive. Updating it triggers an automatic re-render:

# Replace all data
chart.data = new_data

# Append a single row
chart.append_data({"month": "Jun", "sales": 300})

# Update a specific row
chart.update_data(0, {"month": "Jan", "sales": 120})

# Clear all data
chart.clear_data()

Complete example¶

A sales dashboard with a bar chart, trend line, and live data updates:

import nib
import random


def main(app: nib.App):
    app.title = "Sales"
    app.icon = nib.SFSymbol("chart.bar.fill")
    app.width = 400
    app.height = 450

    data = [
        {"month": "Jan", "sales": 120, "target": 100},
        {"month": "Feb", "sales": 150, "target": 130},
        {"month": "Mar", "sales": 180, "target": 160},
        {"month": "Apr", "sales": 160, "target": 170},
        {"month": "May", "sales": 210, "target": 190},
        {"month": "Jun", "sales": 240, "target": 220},
    ]

    chart = nib.Chart(
        data=data,
        marks=[
            nib.BarMark(
                x="month", y="sales",
                foreground_style="#3B82F6",
                corner_radius=4,
            ),
            nib.LineMark(
                x="month", y="target",
                foreground_style="#EF4444",
                line_width=2,
                symbol=nib.SymbolShape.CIRCLE,
                interpolation=nib.InterpolationMethod.MONOTONE,
            ),
        ],
        x_axis=nib.ChartAxis(label="Month"),
        y_axis=nib.ChartAxis(
            label="Units Sold",
            grid_lines=True,
            grid_color="#e5e7eb",
        ),
        chart_background="#ffffff",
        width=370,
        height=250,
        padding=8,
        corner_radius=12,
    )

    total_label = nib.Text(
        f"Total: {sum(d['sales'] for d in data)} units",
        font=nib.Font.HEADLINE,
    )

    # Donut chart for breakdown
    pie_data = [
        {"category": "Online", "value": 450},
        {"category": "Retail", "value": 320},
        {"category": "Wholesale", "value": 290},
    ]

    donut = nib.Chart(
        data=pie_data,
        marks=[
            nib.SectorMark(
                angle="value",
                foreground_style=nib.PlottableField("category"),
                inner_radius=40,
                outer_radius=70,
                corner_radius=3,
            ),
        ],
        legend=nib.ChartLegend(position="bottom"),
        width=370,
        height=160,
    )

    app.build(
        nib.VStack(
            controls=[
                total_label,
                chart,
                nib.Text("Sales by Channel", font=nib.Font.SUBHEADLINE),
                donut,
            ],
            spacing=12,
            padding=16,
        )
    )


nib.run(main)