UI kit and motion
PyWeb comes with a component kit: accessible, themed, server-rendered components in the spirit of shadcn/ui and Radix. It also comes with a motion system in the spirit of motion.dev. Both are plain .pyweb code and CSS variables, so you can change them at every level, from one line of theme to owning a component's source.
from pyweb import App
from pyweb.ui import Badge, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Theme
app = App(title="Billing", theme=Theme(accent="#6366f1", radius=10))
@app.page("/")
def Billing():
<Card>
<CardHeader>
<CardTitle>Pro plan</CardTitle>
<CardDescription>Renews on 1 November</CardDescription>
</CardHeader>
<CardContent>
<Badge tone="success">Active</Badge>
<Button variant="outline" href="/plans">Change plan</Button>
</CardContent>
</Card>What this compiles to
// Billing.js
// card.pyweb
const { Card, CardHeader, CardTitle, CardDescription, CardContent } = (() => {
function Card($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("div", {"class": "pw-card", "data-pw-ui": "card", "data-part": "card", "$spread3": () => attrs()}, () => [$dyn(() => children())])];
}
function CardHeader($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("div", {"data-part": "header", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
function CardTitle($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("h3", {"data-part": "title", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
function CardDescription($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("p", {"data-part": "description", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
function CardContent($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("div", {"data-part": "content", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
return { Card, CardHeader, CardTitle, CardDescription, CardContent };
})();
// display.pyweb
const { Badge } = (() => {
function Badge($p) {
const variant = $p["variant"] || (() => "soft");
const tone = $p["tone"] || (() => null);
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("span", {"class": "pw-badge", "data-part": "badge", "data-variant": () => variant(), "data-tone": () => tone(), "$spread4": () => attrs()}, () => [$dyn(() => children())])];
}
return { Badge };
})();
// button.pyweb
const { Button } = (() => {
function Button($p) {
const variant = $p["variant"] || (() => "default");
const size = $p["size"] || (() => "md");
const type = $p["type"] || (() => "button");
const href = $p["href"] || (() => null);
const loading = $p["loading"] || (() => false);
const disabled = $p["disabled"] || (() => false);
const onclick = $p["onclick"] || (() => null);
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
const busy = $computed(() => ($py.truth(loading()) ? "true" : null));
const part = $computed(() => $py.or($py.m(attrs(), "get", "data-part"), () => "button"));
return [$when(() => $py.truth(href()), () => [$h("a", {"class": "pw-button", "data-part": () => part(), "data-variant": () => variant(), "data-size": () => size(), "href": () => href(), "aria-disabled": () => ($py.truth(disabled()) ? "true" : null), "onclick": (e) => { const f = onclick(); return f ? f(e) : undefined; }, "$spread7": () => attrs()}, () => [$dyn(() => children())])], () => [$h("button", {"class": "pw-button", "data-part": () => part(), "data-variant": () => variant(), "data-size": () => size(), "type": () => type(), "disabled": () => $py.or(disabled(), () => loading()), "aria-busy": () => busy(), "onclick": (e) => { const f = onclick(); return f ? f(e) : undefined; }, "$spread8": () => attrs()}, () => [
$when(() => $py.truth(loading()), () => [$h("span", {"class": "pw-spinner", "aria-hidden": "true"})]),
$dyn(() => children())
])])];
}
return { Button };
})();
function Billing($s) {
return [Card({"children": () => [
CardHeader({"children": () => [
CardTitle({"children": () => [$t("Pro plan")]}),
CardDescription({"children": () => [$t("Renews on 1 November")]})
]}),
CardContent({"children": () => [
Badge({"tone": () => "success", "children": () => [$t("Active")]}),
Button({"variant": () => "outline", "href": () => "/plans", "children": () => [$t("Change plan")]})
]})
]})];
}
$mount("Billing", Billing);page Billing route=/<div data-pw-ui="card" data-part="card" class="pw-card">
<div data-part="header">
<h3 data-part="title">Pro plan</h3>
<p data-part="description">Renews on 1 November</p>
</div><div data-part="content">
<span data-part="badge" data-variant="soft" data-tone="success" class="pw-badge">Active</span><a data-part="button" data-variant="outline" data-size="md" href="/plans" class="pw-button">Change plan</a></div></div>See it: the UI kit and motion example (examples/ui/app.pyweb, also in the playground and as a live demo on the website) tours the components and the animations. The pyweb new templates use the kit too: todo animates its rows, and saas has a sidebar layout, an account menu, a dialog, toasts and animated live tasks. The sign-in, account and /admin pages are built from the same classes and follow your theme.
With an AI assistant: the pyweb_ui MCP tool lists every component with its variants and sizes, shows one component's parameters and source (pyweb://kit/<Component>), copies one into your app and makes a theme; pyweb_review screenshots a page in light and dark at desktop and phone widths with an accessibility audit; the design_pass prompt puts them together.
Pages that use the kit get its stylesheet (/__pyweb/ui.css, about 9 KB gzipped) and the theme (/__pyweb/theme.css); pages that don't use it get neither.
#The theme
App(theme=Theme(...)) sets the look of every kit component and of the auth pages:
| Setting | Default | |
|---|---|---|
accent | "#6366f1" | your brand colour |
gray | tinted toward the accent | the neutral's hue |
radius | 10 | corner radius, in px |
font | "system" | "system", "inter", "serif", "mono" or any CSS font-family |
density | "comfortable" | "compact", "comfortable" or "spacious" |
dark | "auto" | follow the OS, or always "light"/"dark" |
Theme.preset("zinc") (or App(theme="zinc")) picks a built-in look: indigo, zinc, slate, rose, ocean, violet, emerald or amber. Theme.preset("rose", radius=4) changes one value of a preset.
From one accent, PyWeb computes 12-step colour scales (as Radix Colors does) for the accent, a matching gray and the status colours (danger, success, warning, info), in light and dark. It works in OKLCH, so the steps look evenly spaced. Every scale is checked for contrast: text steps and text on solid fills reach 4.5:1, and are adjusted when a colour falls short.
| Steps | Use |
|---|---|
| 1-2 | app and subtle backgrounds |
| 3-5 | component backgrounds: normal, hover, pressed |
| 6-8 | borders and focus rings |
| 9-10 | solid fills (buttons): normal, hover |
| 11-12 | coloured and high-contrast text |
Everything is a CSS variable, so plain CSS can change any of it: --pw-accent-1 ... --pw-accent-12, --pw-gray-*, --pw-danger-*, --pw-bg, --pw-fg, --pw-fg-muted, --pw-border, --pw-ring, --pw-radius, --pw-font, --pw-space-1 ... --pw-space-12, --pw-shadow-1 ... --pw-shadow-3. Setting data-theme="dark" (or "light") on <html> overrides the OS setting.
#Components
| Import | |
|---|---|
Button, ButtonGroup | variant: default, secondary, outline, ghost, link, destructive. size: sm, md, lg, icon. href= makes a link that looks like a button; loading= shows a spinner and disables it |
Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter | |
Badge | variant: soft, solid, outline, secondary. tone: danger, success, warning |
Alert, AlertTitle, AlertDescription | tone: danger, success, warning, info (danger and warning are announced to screen readers) |
Separator | orientation, decorative |
Skeleton | width, height, radius |
Kbd, Label, Avatar (src, alt, fallback, size), AspectRatio (ratio), Progress (value, max, label) | |
Image | src, alt (required), width, height, sizes, priority. See Images |
Stepper, Step | a form in steps: Step(title=); Stepper(submit=, next=, back=, default=). See Forms |
The form tags (<Form>, <Input>, <Textarea>, <Select>, <Checkbox>, <Submit>, from pyweb) are styled by the kit too.
#Overlays
from pyweb import App
from pyweb.ui import (Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter,
DialogHeader, DialogTitle, DialogTrigger)
app = App(title="Profile")
@app.page("/")
def Profile():
<Dialog>
<DialogTrigger>Edit profile</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Edit profile</DialogTitle>
<DialogDescription>Changes are saved when you press Done.</DialogDescription>
</DialogHeader>
<input value="Ada" aria-label="Name" />
<DialogFooter><DialogClose>Done</DialogClose></DialogFooter>
</DialogContent>
</Dialog>What this compiles to
// Profile.js
// dialog.pyweb
const { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose } = (() => {
function Dialog($p) {
const open = $p["open"] || (() => null);
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
const state = $computed(() => ((open() == null) ? null : ($py.truth(open()) ? "true" : "false")));
return [$h("div", {"class": "pw-dialog-root", "data-pw-ui": "dialog", "data-part": "root", "data-state": "closed", "data-open": () => state(), "$spread5": () => attrs()}, () => [$dyn(() => children())])];
}
function DialogTrigger($p) {
const variant = $p["variant"] || (() => "default");
const size = $p["size"] || (() => "md");
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("button", {"type": "button", "class": "pw-button", "data-part": "trigger", "data-variant": () => variant(), "data-size": () => size(), "$spread5": () => attrs()}, () => [$dyn(() => children())])];
}
function DialogContent($p) {
const close_button = $p["close_button"] || (() => true);
const size = $p["size"] || (() => "md");
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("dialog", {"class": "pw-dialog", "data-part": "content", "data-state": "closed", "data-size": () => size(), "$spread4": () => attrs()}, () => [
$dyn(() => children()),
$when(() => $py.truth(close_button()), () => [$h("button", {"type": "button", "class": "pw-dialog-x", "data-part": "close", "aria-label": "Close"}, () => [$h("svg", {"width": "15", "height": "15", "viewBox": "0 0 15 15", "aria-hidden": "true"}, () => [$h("path", {"d": "M11.8 3.2 3.2 11.8M3.2 3.2l8.6 8.6", "stroke": "currentColor", "stroke-width": "1.5", "stroke-linecap": "round"})])])])
])];
}
function DialogHeader($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("div", {"data-part": "header", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
function DialogTitle($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("h2", {"data-part": "title", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
function DialogDescription($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("p", {"data-part": "description", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
function DialogFooter($p) {
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("div", {"data-part": "footer", "$spread1": () => attrs()}, () => [$dyn(() => children())])];
}
function DialogClose($p) {
const variant = $p["variant"] || (() => "outline");
const size = $p["size"] || (() => "md");
const children = $p["children"] || (() => null);
const attrs = $p["$rest"] || (() => ({}));
return [$h("button", {"type": "button", "class": "pw-button", "data-part": "close", "data-variant": () => variant(), "data-size": () => size(), "$spread5": () => attrs()}, () => [$dyn(() => children())])];
}
return { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose };
})();
function Profile($s) {
return [Dialog({"children": () => [
DialogTrigger({"children": () => [$t("Edit profile")]}),
DialogContent({"children": () => [
DialogHeader({"children": () => [
DialogTitle({"children": () => [$t("Edit profile")]}),
DialogDescription({"children": () => [$t("Changes are saved when you press Done.")]})
]}),
$h("input", {"value": "Ada", "aria-label": "Name"}),
DialogFooter({"children": () => [DialogClose({"children": () => [$t("Done")]})]})
]})
]})];
}
$mount("Profile", Profile);page Profile route=/<div data-pw-ui="dialog" data-part="root" data-state="closed" class="pw-dialog-root">
<button type="button" data-part="trigger" data-variant="default" data-size="md" class="pw-button">Edit profile</button>
<dialog data-part="content" data-state="closed" data-size="md" class="pw-dialog"><div data-part="header">
<h2 data-part="title">Edit profile</h2>
<p data-part="description">Changes are saved when you press Done.</p>
</div><input value="Ada" aria-label="Name"><div data-part="footer">
<button type="button" data-part="close" data-variant="outline" data-size="md" class="pw-button">Done</button>
</div><button type="button" class="pw-dialog-x" data-part="close" aria-label="Close"><svg width="15" height="15" viewBox="0 0 15 15" aria-hidden="true"><path d="M11.8 3.2 3.2 11.8M3.2 3.2l8.6 8.6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg></button>
</dialog></div>| Component | Parts |
|---|---|
Dialog | DialogTrigger, DialogContent (size: sm, md, lg, full), DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose |
AlertDialog | AlertDialogTrigger, AlertDialogContent, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogCancel, AlertDialogAction |
Sheet | SheetTrigger, SheetContent (side: right, left, top, bottom), SheetHeader, SheetTitle, SheetDescription, SheetFooter, SheetClose |
Popover (side, align, offset) | PopoverTrigger, PopoverContent (arrow), PopoverClose |
Tooltip (text, side, delay) | wraps the element it describes; or TooltipTrigger, TooltipContent |
HoverCard | HoverCardTrigger (a link), HoverCardContent |
DropdownMenu (side, align) | DropdownMenuTrigger, DropdownMenuContent |
ContextMenu | ContextMenuTrigger (the area to right-click), ContextMenuContent |
Menubar | MenubarMenu, MenubarTrigger, MenubarContent |
| menu items (all three menus) | MenuItem (shortcut, disabled, keep_open), MenuCheckboxItem (checked), MenuRadioGroup, MenuRadioItem (value), MenuLabel, MenuSeparator, MenuSub, MenuSubTrigger, MenuSubContent |
They follow the WAI-ARIA Authoring Practices for each pattern:
- Dialogs keep focus inside, close on Escape or a click outside (alert dialogs don't: they focus Cancel), and give focus back to what opened them. They're built on the native
<dialog>, so the rest of the page is inert while one is open. - Menus open with Enter, Space or the arrow keys. Arrows, Home/End and typing the first letters move. Enter chooses, ArrowRight and ArrowLeft open and close submenus, and Escape or Tab close.
- Popovers, menus and tooltips flip to the other side when there isn't room, stay inside the window, and size themselves to the space available.
Every *Trigger is a button that takes variant/size; any element with data-part="trigger" inside the root works too (<Button data-part="trigger">).
Controlled and events. open={flag} on Dialog, AlertDialog, Sheet and Popover opens and closes them when flag changes. Every root fires openchange (onopenchange={handler}, with event.detail.open). Checkbox items fire checkedchange (event.detail.checked); radio groups and pickers fire valuechange (event.detail.value).
#Pickers
| Component | |
|---|---|
SelectMenu (name, value, placeholder) + SelectOption (value, label, disabled) | a styled select. Typing picks options, and it works in forms through name |
Combobox (name, value, placeholder, filter) + ComboboxOption, ComboboxEmpty | type to filter (filter="server" when your oninput renders new options) |
Command / CommandDialog (shortcut, default ⌘K / Ctrl+K) + CommandInput, CommandList, CommandEmpty, CommandGroup (heading), CommandItem (keywords, shortcut, onclick), CommandSeparator | a command palette: results are ranked as you type (fuzzy, with keywords), and Enter or a click runs one |
#Toasts
from pyweb import server
from pyweb.ui import toast
@server
def save(text: str) -> None:
...
toast("Saved", "Your changes are live.", tone="success")toast(title, description=None, tone=None, duration=5000, action=None) works in server functions, form actions and pages; the page that gets the answer shows it (after a form's redirect too). tone is success, danger, warning or info; duration=0 keeps it until dismissed; action={"label": "Undo", "href": "/undo/42"} adds a button. Put a <Toaster position="bottom-right" /> in your layout to choose where toasts appear (it's added for you otherwise). Toasts stack and spread out on hover, pause while hovered or focused, can be swiped away, and are announced to screen readers (danger ones at once). Browser code can call pywebUI.toast({"title": "Copied"}).
Each component's behaviour is a small module (0.3-3 KB gzipped) that loads only on pages that use that component.
#Tabs, accordions and collapsibles
<Tabs default="account">
<TabsList>
<TabsTrigger value="account">Account</TabsTrigger>
<TabsTrigger value="password">Password</TabsTrigger>
</TabsList>
<TabsContent value="account">...</TabsContent>
<TabsContent value="password">...</TabsContent>
</Tabs>
<Accordion type="single" default="shipping">
<AccordionItem value="shipping">
<AccordionTrigger>How long does shipping take?</AccordionTrigger>
<AccordionContent>Two to four days.</AccordionContent>
</AccordionItem>
</Accordion>| Component | |
|---|---|
Tabs (default, value, orientation, activation) + TabsList, TabsTrigger (value, disabled), TabsContent (value) | arrow keys move between tabs and show them (activation="manual": Enter shows), Home/End jump; the underline slides to the chosen tab. Put the default tab first: it shows until scripts load |
Accordion (type: single or multiple, default, value, collapsible) + AccordionItem (value, open, disabled), AccordionTrigger, AccordionContent | native <details>: works without scripts, and find-in-page opens a closed section. Height animates; arrows move between headers |
Collapsible (open) + CollapsibleTrigger, CollapsibleContent | one section that opens and closes |
value= makes Tabs and Accordion controlled: they fire valuechange and show what your state says.
#Form controls
Native inputs underneath (forms, validation, keyboard and screen readers come from the browser), styled by the kit. With name= they're sent with any form.
| Component | |
|---|---|
Checkbox (label, checked, indeterminate, name, value) | indeterminate= shows the mixed state |
Switch (label, checked, name, size) | a checkbox with role="switch" |
RadioGroup (name, value, options, orientation) | options=[("free", "Free"), ...], or RadioGroupItem (value, label) children |
Toggle (pressed, default, variant, label) | a button that stays pressed; fires pressedchange |
ToggleGroup (type: single or multiple, value, default, name) + ToggleGroupItem (value, label) | single works like radio buttons; fires valuechange |
Slider (value, min, max, step, name, label, show_value) | a range input with a filled track |
InputOTP (length, name, pattern: digits or alphanumeric, group) | one real autocomplete="one-time-code" input drawn as boxes (paste and SMS autofill work); fires complete |
#Layout and navigation
<SidebarProvider>
<Sidebar>
<SidebarHeader>Acme</SidebarHeader>
<SidebarContent>
<SidebarGroup label="Workspace">
<SidebarMenu>
<SidebarMenuItem>
<SidebarMenuButton href="/" active={True} icon="⌂">Home</SidebarMenuButton>
</SidebarMenuItem>
</SidebarMenu>
</SidebarGroup>
</SidebarContent>
<SidebarFooter>...</SidebarFooter>
</Sidebar>
<SidebarInset>
<SidebarTrigger />
...the page...
</SidebarInset>
</SidebarProvider>| Component | |
|---|---|
SidebarProvider (collapsed, collapsible: icon, offcanvas or none, side, variant: sidebar or floating, shortcut) + Sidebar, SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup (label), SidebarMenu, SidebarMenuItem, SidebarMenuButton (href, active, icon, badge), SidebarSeparator, SidebarTrigger, SidebarRail, SidebarInset | SidebarTrigger or Ctrl/⌘+B collapses it to icons (remembered in the browser). On small screens it opens over the page instead |
NavigationMenu + NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink (href, description, active) | a site menu: panels open on hover or click, arrows move along the bar, ArrowDown enters a panel, Escape closes |
Breadcrumb + BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis | |
Pagination (page, pages, href or onchange, siblings) | links (href="?page=" gets the number added) or buttons that call onchange(n), with ellipses for long ranges |
ResizablePanelGroup (direction, save) + ResizablePanel (size, min, max, collapsible), ResizableHandle (grip) | drag or use the arrow keys on a handle (sizes are percentages); save="name" remembers them |
ScrollArea (height, max_height, orientation) | a scrolling region with thin scrollbars, reachable by keyboard |
#Dates
<Calendar name="due" value="2026-11-02" />
<DatePicker name="trip" mode="range" placeholder="Pick dates" onvaluechange={changed} />Calendar and DatePicker take value (an ISO date; a range is "start/end"), name, mode (single or range), min, max, week_start (0 Sunday, 1 Monday; the locale decides otherwise) and locale. Arrow keys move a day or a week, Home/End go to the week's ends, PageUp/PageDown change the month (with Shift, the year), and Enter picks. Without scripts a Calendar is a native date field.
#Carousel
<Carousel loop={True} label="Featured">
<CarouselContent>
for p in products:
<CarouselItem basis="33%"><ProductCard product={p} /></CarouselItem>
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
<CarouselDots />
</Carousel>Slides sit on a scroll-snap track, so swipes and trackpads work as they do anywhere else. Buttons, dots and the arrow keys move one slide; autoplay=5000 advances on a timer, paused while hovered or focused and never with reduced motion. It fires slidechange.
#Data tables
<DataTable rows={tasks} page_size={10} selectable={True} onselect={picked} columns={[
{"key": "title", "label": "Task"},
{"key": "points", "label": "Points", "align": "end"},
{"key": "done", "label": "Done", "format": lambda v: "✓" if v else "", "sortable": False},
]} />Search, sorting (click a header: ascending, descending, off), pages and row selection all run in the browser; the first page is rendered on the server. rows is a list of dicts. A live query works: the table follows it. onselect(keys) gets the key (default "id") of every selected row. export="csv" adds a "Download CSV" button: the rows that match the search, in the table's order (filename="tasks.csv"); the admin has the same per Model, and a route can send one with pyweb.routes.csv(rows). For a plain styled table there are Table (caption), TableHeader, TableBody, TableFooter, TableRow (selected), TableHead and TableCell (align).
#Images
<Image src="/static/team.jpg" alt="The team at the offsite" width={800} height={450} />width and height are the size it shows at, so the page doesn't jump while it loads. For a file in static/, the browser gets a srcset of smaller copies (320 to 2560 pixels wide) and picks the one that fits the screen; the server makes them on first request with Pillow (pip install "pyweb-stack[images]"), never larger than the original and without the photo's metadata (camera, location), and keeps them in memory. Without Pillow the original is sent. Images load when scrolled to; priority={True} loads the first big image of a page at once.
#Charts
<BarChart data={sales} x="month" y={["online", "store"]} label="Sales by month" />
<LineChart data={visits} x="day" y="visits" />
<AreaChart data={visits} x="day" y="visits" />
<PieChart data={plans} name="plan" value="users" donut={True} center="1,204" />
<Sparkline values={[3, 5, 2, 8, 6]} />Charts are SVG drawn on the server: no chart library and nothing to load. They redraw when their data changes (state or a live query). BarChart takes stacked=, LineChart takes area= and dots=, and each takes height, colors, format (a function for the numbers on the axis and in tooltips) and legend. Colours come from --pw-chart-1 ... --pw-chart-5 (accent, info, success, warning, danger). Each chart has a label and a hidden table of its numbers for screen readers, and every bar, point and slice has a tooltip.
from pyweb.ui import * imports every component; pages still only get the components they use.
#Customising
Each level is optional; most apps stop at the first.
- The theme.
Theme(...), a preset, or CSS variables. Inpyweb dev, the toolbar's Theme tab changes the accent, gray, radius, font, density and dark mode on the running app as you drag. "Copy as code" gives theTheme(...)line; "Save to app.pyweb" writes it into yourApp(...)call. Nothing else in the file changes. - Props.
variant=,size=andtone=on components (the editor completes the values and warns about unknown ones). Any other attribute (id,aria-*,data-*, handlers) reaches the element, andclass_=adds your classes to the kit's. - Your own variants of kit components.
ui.extendadds them, as CSS in the theme stylesheet: Then<Button variant="brand" size="xl">works, and the editor completes it. Sub-dicts namedhover,focus,active,disabled,openorcheckedstyle that state.Theme(extend={"Button": {"variant": {...}}})does the same from the theme.Pythonfrom pyweb import ui ui.extend("Button", variant={ "brand": {"background": "var(--pw-accent-11)", "color": "white", "hover": {"background": "var(--pw-accent-12)"}}, }, size={"xl": {"height": "52px", "padding": "0 28px"}}) - Variants for your own components (like cva, and tailwind-merge's core):
variants()describes the classes,style()picks them, andcx()joins classes, the last of a conflicting group winning. They work in server code and browser code alike: In the component,class={style(card, variant=variant, size=size, class_=class_)}gives the classes, and the caller'sclass_wins conflicts (p-10replacesp-4). Options arevariant,size,toneandshape.Pythonfrom pyweb.ui import cx, variants, style card = variants( base="rounded-lg border p-4", variant={"plain": "bg-white", "brand": "bg-indigo-600 text-white"}, size={"sm": "p-2 text-sm", "lg": "p-6"}, default={"variant": "plain"}, compound=[{"variant": "brand", "size": "lg", "class": "shadow-lg"}], ) - State and part attributes. Every element marks its part and state (
data-part="title",data-variant="outline",data-state="open"), so CSS can style any part in any state: The kit's CSS lives in thepywebcascade layer, so any CSS you write wins, however specific its selectors.css.pw-button[data-variant="outline"] { border-width: 2px; } .pw-card [data-part="title"] { font-family: "Fraunces", serif; } - Own the code.
pyweb ui add buttoncopies the component's.pywebfile intocomponents/. Change it as you like and import it from there (from components.button import Button).pyweb ui diff buttonshows how your copy differs from the kit after an upgrade;pyweb ui listlists everything in the kit.
Motion follows the same ladder:
- Global:
App(motion=Motion(...)). - Named: presets, including your own (
pyweb.motion.preset). - Per element:
transition={{...}}. - Visual tuning: in
pyweb dev, the toolbar's Motion tab picks any animated element and changes its spring or duration with sliders. Each change replays the animation. "Copy as code" gives thetransition={{...}}.
Plain functions in other .pyweb files can be imported into browser code too (from formatting import money), along with the functions and constants they use.
#Accessibility checks
pyweb check and the editor point out:
- images without
alt; - clicks on elements a keyboard can't reach (use
<Button>); - form fields without a label;
- buttons and links with no text;
- a positive
tabindex; - an empty
App(lang=...).
They're warnings; pyweb check --strict fails on them. The kit, examples and templates pass.
#Motion
Animations are attributes on any element:
from pyweb import App
app = App(title="Tasks")
@app.page("/")
def Tasks():
tasks = ["Write docs", "Ship 0.6"]
def add():
tasks = tasks + [f"Task {len(tasks) + 1}"]
<main>
<button onclick={add} while_hover={{"scale": 1.05}} while_tap={{"scale": 0.95}}>Add</button>
<ul>
for t in tasks:
<li initial={{"opacity": 0, "y": 12}} animate={{"opacity": 1, "y": 0}}
exit={{"opacity": 0, "x": -40}} layout>{t}</li>
</ul>
</main>What this compiles to
// Tasks.js
function Tasks($s) {
const tasks = $signal("tasks" in $s ? $s["tasks"] : ["Write docs", "Ship 0.6"], "tasks");
function add() {
tasks($py.add(tasks(), [`Task ${$py.str(($py.len(tasks()) + 1))}`]));
}
return [$h("main", null, () => [
$h("button", {"onclick": add, "data-pw-motion": JSON.stringify({"while_hover": {"scale": 1.05}, "while_tap": {"scale": 0.95}})}, () => [$t("Add")]),
$h("ul", null, () => [$list(() => tasks(), (t) => [$h("li", {"data-pw-motion": JSON.stringify({"initial": {"opacity": 0, "y": 12}, "animate": {"opacity": 1, "y": 0}, "exit": {"opacity": 0, "x": (-40)}, "layout": true}), "style": ((i, s) => s)({"opacity": 0, "y": 12}, null, null, {"opacity": 1, "y": 0})}, () => [$t($py.text(t))])])])
])];
}
$mount("Tasks", Tasks);page Tasks route=/
browser tasks reactive state: assigned in add(); literal initial value
browser add event handler (compiled to JavaScript)<main>
<button data-pw-motion="{"while_hover":{"scale":1.05},"while_tap":{"scale":0.95}}">Add</button>
<ul>
<li data-pw-motion="{"initial":{"opacity":0,"y":12},"animate":{"opacity":1,"y":0},"exit":{"opacity":0,"x":-40},"layout":true}" style="translate: 0px 12px; opacity: 0">Write docs</li>
<li data-pw-motion="{"initial":{"opacity":0,"y":12},"animate":{"opacity":1,"y":0},"exit":{"opacity":0,"x":-40},"layout":true}" style="translate: 0px 12px; opacity: 0">Ship 0.6</li>
</ul></main>A new row slides in, a removed one slides out before it leaves the page, and the others glide to their new places.
| Attribute | |
|---|---|
initial | the pose it starts in (rendered by the server, so the first paint already starts there). initial={False} starts at animate |
animate | the pose to animate to. When the value changes (animate={{"x": x}}), it animates there from wherever it is |
exit | the pose to animate to before it's removed (an if turning false, a row leaving a for) |
transition | how: {"type": "spring", "stiffness": 300, "damping": 24}, {"type": "spring", "duration": 0.4, "bounce": 0.3}, {"type": "tween", "duration": 0.3, "ease": "ease-out"}, plus delay, repeat (a number, or "infinite"), repeat_type ("loop", "reverse"), and per value ({"opacity": {"duration": 0.2}}) |
while_hover, while_tap, while_focus, while_in_view | poses held while the pointer is over it, while pressed (Enter and Space too), while keyboard-focused, while on screen (viewport={{"once": True, "amount": 0.3}}) |
variants | named poses: initial="hidden" animate="show". Children with variants follow their parent's label; the parent's transition={{"stagger_children": 0.05}} (and delay_children) staggers them |
layout | animates every change in its position and size (a reorder, an element opening above it). layout="position" animates only position |
layout_id | an element that appears with the same id as one that just went starts where that one was (a tab underline sliding between tabs). Across pages, client navigation morphs them |
drag | drag, drag="x" or drag="y", with drag_constraints ({"left": -100, "right": 100} or "parent"), drag_elastic (0-1), drag_momentum (default on) and drag_snap_back. It fires dragstart, drag and dragend |
Values are x, y (px, or a string like "100%"), scale, scale_x, scale_y, rotate, rotate_x, rotate_y (degrees), opacity, blur, and any CSS property ("background_color": "#ff0", "height": "auto"). A list is keyframes: animate={{"x": [0, -8, 8, 0]}}. Physical values (position, scale, rotation) move on springs by default, and others on tweens. Interrupting an animation keeps its momentum: the next one starts from where the element is, at the speed it was going.
Presets. animate="fade-up" uses a built-in animation, which sets the initial, animate and exit poses: fade, fade-up, fade-down, fade-left, fade-right, slide-up, slide-down, slide-left, slide-right, scale, pop, blur-in, flip, collapse, shake, pulse. animate="count" makes a number count from its old value to its new one whenever it changes (<span animate="count">{total}</span>). Add your own with pyweb.motion.preset("hero-in", {"initial": {...}, "animate": {...}}).
Components. Motion attributes on a component reach its root element, so <Card animate="fade-up"> works with every kit component. motion={False} turns a kit component's own animations off.
Page transitions. Client navigation runs inside the browser's View Transitions where available (a cross-fade by default; style it with ::view-transition-*). Elements with the same layout_id on both pages morph into each other.
The whole app at once. App(motion=Motion(feel="gentle", speed=0.8, reduced="auto")) (from pyweb.motion import Motion) changes every animation, the kit's included:
feelis "snappy" (default), "gentle", "bouncy", or "none" (no animation);speedscales every duration;reduced="auto"follows the visitor's reduced-motion setting, so movement jumps and fades stay short."always"reduces for everyone, and"never"ignores the setting.
Browser code. from pyweb.motion import animate, timeline, stagger, scroll_progress, use_transform (in event handlers and other browser code):
animate(".row", {"x": [0, 12, 0]}, {"delay": stagger(0.05)})
timeline([["#title", {"opacity": 1}], ["#body", {"y": 0}, {"at": 0.2}]])
progress = scroll_progress() # call progress() to read 0..1
width = use_transform(progress, [0, 1], [0, 100])Without scripts, every animated element shows in its final pose. Animations change only opacity, translate, scale, rotate, filter and transform where they can, which the browser runs off the main thread. The engine is about 7.5 KB gzipped (layout, drag and counting load only on pages that use them), and pages without motion don't load it.