UI components¶
Presentational, shadcn-styled, server-rendered builders. Each returns an HTML string and runs its arguments through Golit's renderer, so components nest with DataFrames, charts, and each other. See the UI components tutorial.
Presentational components — golit.ui.
Unlike widgets (reactive inputs), these are pure builders a view returns: they
take renderables and produce shadcn-styled, server-rendered HTML that slots into
the fragment pipeline. Any argument is run through :func:render_value, so you can
nest a DataFrame, a chart figure, another component, or trusted HTML uniformly::
import golit.ui as ui
@app.view
def panel(by_region, total):
return ui.card(
ui.columns([ui.metric("Revenue", f"${total:,}", delta="+8%"), chart_fig]),
title="Overview",
)
Layout (card/columns/grid/tabs/expander/accordion/divider), display (metric/scorecard/alert/badge/progress/skeleton/spinner), and rich data (table/markdown/code/json_view/heading/caption).
card(
*body: Any,
title: str | None = None,
subtitle: str | None = None,
footer: Any = None,
) -> str
A surface card with optional title/subtitle/footer.
Source code in python/golit/ui.py
Lay renderables out in a responsive row. widths (summing to 12) gives a
custom split; otherwise the columns are equal and stack on small screens.
Source code in python/golit/ui.py
A fixed-column responsive grid (1 → 2 → cols across breakpoints).
Source code in python/golit/ui.py
A client-side tab group (Alpine). panels maps label → renderable.
Source code in python/golit/ui.py
A collapsible section (native <details> — no JS needed).
Source code in python/golit/ui.py
A stack of independently collapsible sections.
Source code in python/golit/ui.py
A horizontal rule, optionally with a centered label.
Source code in python/golit/ui.py
metric(
label: str,
value: Any,
*,
delta: Any = None,
delta_color: str = "normal",
help: str | None = None,
) -> str
A KPI: big value, label, and an optional up/down delta. delta_color is
normal (up=good/green), inverse (down=good), or off (neutral).
Source code in python/golit/ui.py
scorecard(
label: str,
value: Any,
*,
delta: Any = None,
delta_color: str = "normal",
icon: str | None = None,
caption: str | None = None,
kind: str = "default",
) -> str
A standalone KPI card: a label, a big value, an optional trend delta, an
optional Material Symbols icon, and an optional caption footer — where
:func:metric is a bare KPI for composing, scorecard is the complete surface you
drop into a :func:grid for a dashboard header row::
ui.grid([
ui.scorecard("Revenue", "$84.2k", delta="+8%", icon="payments", kind="primary"),
ui.scorecard("Churn", "2.1%", delta="-0.4%", delta_color="inverse",
icon="trending_down", caption="vs last month"),
], cols=2)
delta_color behaves as in :func:metric (normal / inverse / off).
kind tints the icon — default / primary / success / warning /
error.
Source code in python/golit/ui.py
A callout. kind is info/success/warning/error.
Source code in python/golit/ui.py
A small status pill.
Source code in python/golit/ui.py
A progress bar. value is out of total (default a 0–1 fraction).
Source code in python/golit/ui.py
A loading placeholder of pulsing bars.
Source code in python/golit/ui.py
An indeterminate spinner with an optional label.
Source code in python/golit/ui.py
table(
df: Any,
*,
max_rows: int = 50,
highlight: str | None = None,
paginate: bool = False,
per_page: int = 10,
page_sizes: tuple[int, ...] = (10, 25, 50, 100),
) -> str
A styled table from a Polars DataFrame; highlight emphasizes a column.
With paginate=True the rows (up to max_rows, materialised into the page)
are paged entirely client-side via Alpine — a per-page selector plus prev/next
controls, with no server round-trip. Raise max_rows to page through more rows;
page_sizes are the per-page choices. Non-DataFrame values fall back to the
default renderer.
Source code in python/golit/ui.py
A monospaced code block with an optional language tag.
Source code in python/golit/ui.py
Pretty-print a JSON-serializable object into a code block.
Source code in python/golit/ui.py
A section heading (levels 1–6).
Source code in python/golit/ui.py
Style a great_tables GT to match golit's shadcn tables, and return it.
Maps golit's Material-3 light surface onto Great Tables' tab_options — clean white body,
a tinted uppercase column-label row, hairline row rules instead of stripes, no outer borders
— so a returned GT sits in the page like a native :func:table. Apply it around your
built table::
return ui.gt_theme(GT(df).tab_header("Sales").fmt_currency("revenue"))
Your own tab_options / formatting stay; only the theme chrome is set. Takes (and returns)
a GT object — duck-typed, so golit needs no great_tables dependency to offer it.
Source code in python/golit/ui.py
chat(
channel: str,
*,
author: str = "You",
title: str | None = None,
placeholder: str = "Message…",
height: int = 384,
) -> str
A live chat panel backed by a WebSocket at /ws/<channel>.
Renders a message log that fills as messages arrive (over HTMX's ws
extension) and an input that sends over the socket. author is the sender's
display name; height is the log height in pixels. By default every message
relays to all clients on the channel; register an @app.on_message(channel)
handler to add bot/assistant/moderation behavior.
Source code in python/golit/ui.py
webcam(
name: str,
*,
title: str | None = None,
height: int = 384,
width: int | None = None,
) -> str
A live video panel showing the server-side stream registered as name with
@app.stream(name) — for webcam / computer-vision views.
Frames arrive as an MJPEG (multipart/x-mixed-replace) response that the browser
plays natively in a plain <img>: no client JS, and the connection is independent of
the reactive graph, so the view never re-renders mid-stream. Pair it with a producer
that reads a camera and draws its detector's output on each frame::
@app.stream("camera")
def camera():
... # yield annotated JPEG bytes or RGB arrays
@app.view
def live() -> str:
return ui.webcam("camera", title="Detections")
height is the display height in pixels; width (optional) caps the width, else it
scales to its container. The frame keeps its aspect ratio (letterboxed, not cropped).
Source code in python/golit/ui.py
camera(
name: str,
*,
title: str | None = None,
height: int = 384,
width: int = 640,
fps: int = 12,
quality: float = 0.6,
) -> str
A live panel that streams the visitor's own webcam up to the server, runs the
processor registered with @app.on_frame(name) on each frame, and shows the result.
The browser grabs the camera with getUserMedia, sends JPEG frames over a WebSocket
(/golit/camera/<name>), and paints each annotated frame the server sends back — keeping
one frame in flight, so a slow processor just lowers the rate. Use this when the camera is on
the client; for a feed produced on the server use :func:webcam instead. Example::
@app.on_frame("detector")
def detect(frame):
... # return an annotated RGB array or JPEG bytes
@app.view
def live() -> str:
return ui.camera("detector", title="Your camera")
width caps the captured/sent frame width in pixels (smaller = faster); height is the
display height; fps is the target capture rate; quality is the JPEG quality (0–1) of
the uploaded frames. Needs a secure context — https or localhost — for camera
access; on insecure origins it shows a notice instead.
Source code in python/golit/ui.py
recorder(
name: str,
*,
title: str | None = None,
max_seconds: int = 30,
hint: str | None = None,
playback: bool = True,
download: bool = True,
) -> str
A microphone recorder: the visitor records a clip, it's uploaded to the server as
16-bit PCM WAV, and the @app.on_audio(name) handler's result is shown back here.
Click to record, click to stop (or it auto-stops at max_seconds). The clip travels over
a WebSocket (/golit/audio/<name>); whatever the handler returns is rendered into the
panel — a transcript, an analysis, any :mod:golit.ui component — or, if it returns audio
bytes, played back in an inline player. The mic mirror of :func:camera. Example::
@app.on_audio("note")
def handle(wav: bytes):
... # decode (stdlib `wave`), transcribe/analyze
return ui.alert("Got it", kind="success")
@app.view
def live() -> str:
return ui.recorder("note", title="Voice note")
max_seconds caps the recording length; hint is an optional caption under the button.
With playback (default) the clip you just recorded is loaded into an inline player so you
can hear it; with download (default) a link saves it as recording.wav. If the handler
returns audio bytes, the player switches to that. Needs a secure context — https
or localhost — for mic access; otherwise it shows a notice.
Source code in python/golit/ui.py
Render a common Markdown subset (headings, emphasis, lists, blockquote, fenced code, links, rules) to styled HTML — no external dependency.
Source code in python/golit/ui.py
793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 | |