UI Customization Guide: Tailwind CSS, shadcn/ui & HTML
PyDataUI gives you complete design freedom. Whether you prefer utility-first styling with Tailwind CSS, pre-built shadcn/ui components, semantic HTML tags in pure Python, or direct raw HTML/SVG templates, you can build any interface without feeling boxed into rigid defaults.
Developer references
For the full component and attribute contract, see the Component Encyclopedia. For framework tokens, class names, dark mode, and cascade rules, see the CSS Reference.
1. Quick Overview
| Customization Layer | How to Use | Example |
|---|---|---|
| Tailwind CSS | Pass class_name="..." to any component |
Box(class_name="p-6 bg-slate-900 rounded-2xl shadow-xl hover:scale-105 transition-all") |
| shadcn/ui Components | Import ShadCard, ShadButton, ShadDialog, etc. |
ShadButton("Save", variant="default", size="lg") |
| Theme Palettes | Set palette="..." on App() |
App(theme="dark", palette="violet") |
| Semantic HTML in Python | Import from pydataui.html |
from pydataui.html import Section, Header, Nav, Svg, Path, H1, P |
| Raw HTML & SVG | Use Html("""<svg>...</svg>""") |
Html('<div class="badge">Live</div>') |
| Custom Tailwind Config | Pass tailwind_config={...} to App() |
App(tailwind_config={"theme": {"extend": {"colors": {"brand": "#ff5722"}}}}) |
| External Styles & Scripts | Pass stylesheets and scripts to App() |
App(stylesheets=["https://fonts.googleapis.com/..."]) |
2. Tailwind CSS Styling
Tailwind CSS Play CDN is loaded by default. Every component accepts the class_name parameter.
Responsive Breakpoints & Flex/Grid
from pydataui import Component, Text
from pydataui.html import Div
grid_layout = Div(
Div(Text("Sidebar"), class_name="w-full md:w-64 bg-slate-100 p-4 rounded-xl"),
Div(Text("Main Content"), class_name="flex-1 bg-white p-6 rounded-xl shadow-sm"),
class_name="flex flex-col md:flex-row gap-6 p-6 max-w-7xl mx-auto"
)
Pythonic Spatial Layout Shorthands (Row, Col, Grid, Spacer)
In PyDataUI v1.2.0+, you can avoid manual Tailwind flex/grid classes by using high-level spatial primitives:
from pydataui import Row, Col, Grid, Spacer, Card, Text
# Intuitive row layout with column spans:
layout = Row(
Col(Card(Text("Sidebar")), span=3), # 3/12 columns
Col(Card(Text("Main Feed")), width="1/2"), # 50% width
Spacer(), # Auto-flex expanding spacer
Col(Card(Text("Details")), width="full"), # Full width on wrap
gap="6",
align="start"
)
Arbitrary Tailwind Values
You can use Tailwind arbitrary value syntax ([...]):
Div(
class_name="h-[450px] w-[95%] bg-[#0a0f1d] border border-cyan-500/30 rounded-[1.5rem] backdrop-blur-md shadow-[0_20px_50px_rgba(8,_112,_184,_0.2)]"
)
Interactive Hover & Transition States
from pydataui.components.shadcn import ShadButton
btn = ShadButton(
"Explore Models",
class_name="bg-gradient-to-r from-violet-600 to-indigo-600 hover:from-violet-700 hover:to-indigo-700 text-white font-semibold px-6 py-3 rounded-xl shadow-lg hover:shadow-violet-500/25 active:scale-95 transition-all duration-200"
)
3. shadcn/ui Theme Palettes & Components
PyDataUI comes with built-in support for shadcn/ui color palettes and design tokens.
Selecting a Theme Palette
Choose a palette when initializing your App:
from pydataui import App
app = App(
title="Data Studio",
theme="dark", # Options: 'light', 'dark', 'auto' (detects system dark mode)
palette="violet" # Options: 'zinc', 'slate', 'blue', 'violet', 'green', 'rose', 'orange'
)
Each palette automatically configures CSS variables for :root and .dark:
- --primary & --primary-foreground
- --secondary & --secondary-foreground
- --card & --card-foreground
- --muted & --muted-foreground
- --accent & --accent-foreground
- --destructive & --destructive-foreground
- --border, --input, --ring, --radius
Built-In shadcn/ui Components
All shadcn components can be imported directly from pydataui.shadcn, pydataui.components.shadcn, or pydataui.components:
from pydataui.shadcn import (
ShadButton,
ShadCard, ShadCardHeader, ShadCardTitle, ShadCardDescription, ShadCardContent, ShadCardFooter,
ShadInput, ShadBadge, ShadDialog, ShadSheet, ShadTabs, ShadSwitch
)
Buttons
from pydataui.shadcn import ShadButton
ShadButton("Primary Button", variant="default")
ShadButton("Destructive Action", variant="destructive")
ShadButton("Outline Option", variant="outline")
ShadButton("Secondary", variant="secondary")
ShadButton("Ghost", variant="ghost")
ShadButton("Link Style", variant="link")
size="default", size="sm", size="lg", size="icon".
Cards
from pydataui.shadcn import (
ShadCard, ShadCardHeader, ShadCardTitle, ShadCardDescription,
ShadCardContent, ShadCardFooter, ShadButton
)
card = ShadCard(
ShadCardHeader(
ShadCardTitle("Model Deployment"),
ShadCardDescription("Manage endpoint scaling and compute clusters.")
),
ShadCardContent(
Text("Current status: Healthy across 3 replicas.")
),
ShadCardFooter(
ShadButton("Scale Up", variant="default")
),
class_name="max-w-md shadow-md"
)
Model Deployment
Manage endpoint scaling and compute clusters.
Modals & Drawers (Dialog & Sheet)
Driven by pure Python state without writing JavaScript:
from pydataui import State
from pydataui.components.shadcn import ShadDialog, ShadSheet, ShadButton
class ModalState(State):
is_open: bool = False
def open_modal(self):
self.is_open = True
def close_modal(self):
self.is_open = False
dialog = ShadDialog(
Text("Do you want to delete this dataset? This action cannot be undone."),
title="Confirm Action",
description="Permanent deletion warning",
open=ModalState.is_open,
on_close=ModalState.close_modal
)
Inputs, Selects, Switches, & Forms
from pydataui.shadcn import (
ShadInput, ShadTextarea, ShadSelect, ShadCheckbox, ShadSwitch, ShadBadge
)
ShadInput(bind=FormState.search_query, placeholder="Search tables...")
ShadSelect(options=["PostgreSQL", "BigQuery", "Snowflake"], bind=FormState.db_type)
ShadSwitch(checked=FormState.enable_cache, label="Enable Query Cache")
ShadBadge("Production", variant="default")
Modern Collapsible Sidebar & Dashboard Layout
Build production AI and data portals with zero frontend plumbing. The sidebar supports icon-only collapsed state, mobile drawer auto-folding, group badges, and user snippets:
from pydataui.shadcn import DashboardLayout, Sidebar, NavGroup, NavItem, Header, MetricCard
@app.page("/")
def home():
return DashboardLayout(
sidebar=Sidebar(
brand={"name": "PyDataUI Platform", "logo": "cpu", "plan": "Enterprise"},
groups=[
NavGroup("Platform", [
NavItem("Model Registry", icon="box", href="/", active=True, badge="14"),
NavItem("Prompt Studio", icon="sparkles", href="/prompts"),
NavItem("Evaluation", icon="activity", href="/eval"),
]),
NavGroup("Operations", [
NavItem("Telemetry", icon="activity", href="/telemetry"),
NavItem("Audit Logs", icon="shield-check", href="/audit"),
]),
],
footer={"name": "PyDataUI Admin", "email": "admin@pydataui.org", "avatar": "UI"},
collapsible="icon"
),
header=Header(
breadcrumbs=["Home", "Models", "Mistral-7B"],
search=True,
actions=[ShadButton("Deploy Model", variant="default")]
),
content=[
MetricCard(title="Inference Latency", value="14.2 ms", delta="-3.1 ms", delta_type="decrease")
]
)
Overlays: DropdownMenu, Popover, Tooltip, and Spotlight (Cmd+K)
Zero JavaScript needed from you. Built-in headless dismiss, click-outside handling, and keyboard shortcuts:
from pydataui.shadcn import (
ShadDropdownMenu, ShadDropdownItem, ShadDropdownSeparator,
ShadPopover, ShadTooltip, ShadCommandPalette
)
# 1. Action Dropdown
dropdown = ShadDropdownMenu(
trigger=ShadButton("Actions", variant="outline"),
content=[
ShadDropdownItem("View Metrics", icon="activity", shortcut="⌘M"),
ShadDropdownItem("Clone Config", icon="box"),
ShadDropdownSeparator(),
ShadDropdownItem("Delete Cluster", icon="x", danger=True)
]
)
# 2. Accessible Tooltip
tooltip = ShadTooltip("GPU Cluster Online", ShadButton("Node #01", size="sm"))
# 3. Spotlight Command Palette
command = ShadCommandPalette(
items=[
{"label": "Deploy Mistral-7B", "category": "Serving", "shortcut": "⌘D"},
{"label": "Export Vector Embeddings", "category": "Data"},
]
)
Precision AI & ML Form Controls
Tune generation hyperparameters, select model inference engines, and navigate tables:
from pydataui.shadcn import ShadSlider, ShadRadioGroup, ShadDatePicker, ShadPagination
# 1. Hyperparameter Slider with live value bubble
temp_slider = ShadSlider(label="Temperature", min_val=0.0, max_val=2.0, step=0.05, value=0.7)
# 2. Model Selection Card Group
model_radio = ShadRadioGroup(
name="model",
value="vllm",
options=[
{"value": "vllm", "label": "vLLM Engine", "description": "High-speed PagedAttention", "badge": "Fast"},
{"value": "tgi", "label": "HuggingFace TGI", "description": "Tensor-parallel optimized"}
]
)
# 3. Date Picker & Pagination
date_filter = ShadDatePicker(label="Run Timestamp", value="2026-11-11")
pagination = ShadPagination(total_pages=5, current_page=2)
High-speed PagedAttention inference server
Tensor-parallel optimized
4. Universal Extensibility Engine: Ingesting Any Upcoming shadcn/ui Component
"Can I use new or upcoming shadcn/ui and community components directly without waiting for PyDataUI framework updates?"
YES. Because shadcn/ui is an open registry of Tailwind CSS classes and HTML elements rather than a compiled npm package, PyDataUI lets you consume new widgets through 4 direct zero-JS pathways:
Pathway 1: Instant JSX / HTML Copy-Paste (from_jsx & from_html)
Whenever you find a snippet on ui.shadcn.com, 21st.dev, or GitHub, paste the raw JSX or HTML code directly into Python:
from pydataui.shadcn import from_jsx
# 1. Paste snippet as a docstring:
UpcomingSparkCard = from_jsx("""
<div className="rounded-xl border bg-card text-card-foreground p-6 shadow-sm hover:shadow-md transition-shadow">
<div className="flex items-center justify-between pb-2">
<h4 className="text-sm font-medium text-muted-foreground">{title}</h4>
<span className="text-xs font-semibold px-2 py-0.5 rounded-full bg-emerald-500/10 text-emerald-400">{status}</span>
</div>
<div className="text-2xl font-bold">{metric}</div>
<p className="text-xs text-muted-foreground mt-1">{subtitle}</p>
<div className="mt-4">{children}</div>
</div>
""")
# 2. Use immediately with typed parameters:
card = UpcomingSparkCard(
title="Daily Active Tokens",
status="Optimal",
metric="4.8M",
subtitle="Processed across 64 H100 nodes",
children=[ShadButton("View Logs", size="sm")]
)
Pathway 2: CLI Component Ingester (pydataui add <component>)
Download and generate a standalone Python component file in your project from the official shadcn JSON registry or any custom URL:
# Add official upcoming shadcn component:
pydataui add carousel
pydataui add resizable
# Add from any direct registry URL:
pydataui add https://ui.shadcn.com/r/styles/default/animated-beam.json
Pathway 3: Pure Python Declarative Factory (create_shadcn_component)
Define custom variants in 4 lines:
from pydataui.shadcn import create_shadcn_component
StatusBadge = create_shadcn_component(
tag="span",
base_classes="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-semibold border",
variants={
"healthy": "bg-emerald-500/10 text-emerald-400 border-emerald-500/20",
"critical": "bg-rose-500/10 text-rose-400 border-rose-500/20",
},
default_variant="healthy"
)
5. Semantic HTML in Pure Python (pydataui.html)
Instead of being restricted to high-level widgets, you can compose standard semantic HTML tags directly in Python using pydataui.html:
from pydataui.html import (
Header, Nav, Main, Section, Footer, Article, Aside,
Div, Span, P, H1, H2, H3, H4, A, Ul, Li,
Svg, Path, Circle, Rect
)
page_layout = Section(
Header(
Nav(
Span("My Brand", class_name="font-extrabold text-xl"),
A("Documentation", href="/docs", class_name="text-sm hover:underline"),
class_name="flex justify-between items-center max-w-7xl mx-auto p-4"
),
class_name="border-b bg-card/80 backdrop-blur-md"
),
Main(
H1("Semantic HTML in Python", class_name="text-3xl font-bold tracking-tight"),
P("Write native tags with Tailwind classes and Python reactivity.", class_name="text-muted-foreground mt-2"),
class_name="p-8 max-w-7xl mx-auto"
),
Footer(
P("© 2026 PyDataUI", class_name="text-center text-xs text-muted-foreground"),
class_name="border-t p-4"
),
class_name="min-h-screen bg-background"
)
SVG Icons & Vector Graphics
Create clean vector icons without external asset bundles:
from pydataui.html import Svg, Path
bolt_icon = Svg(
Path(d="M13 10V3L4 14h7v7l9-11h-7z"),
viewBox="0 0 24 24",
fill="currentColor",
class_name="w-6 h-6 text-amber-500"
)
HTML5 Boolean Attributes
PyDataUI intelligently formats HTML boolean attributes according to HTML5 standards:
- disabled=True renders as disabled
- disabled=False is completely omitted (no invalid disabled="False")
- required=True, checked=True, readonly=True, autofocus=True work out of the box.
5. Raw HTML & Custom Templates (Html / RawHtml)
If you have existing HTML snippets, complex SVG graphics, or third-party web embeds, use Html:
from pydataui import Html
custom_embed = Html("""
<div class="relative overflow-hidden rounded-2xl bg-slate-900 p-8 text-white shadow-2xl">
<div class="absolute -right-10 -top-10 h-40 w-40 rounded-full bg-violet-600/30 blur-3xl"></div>
<h3 class="text-xl font-bold">Hardware Accelerated Streaming</h3>
<p class="text-slate-400 text-sm mt-2">Zero JavaScript required on the client side.</p>
</div>
""")
6. Application-Level Customization (App Configuration)
Customize fonts, third-party libraries, and Tailwind themes directly when creating the App:
from pydataui import App
app = App(
title="Analytics Portal",
theme="dark", # 'light', 'dark', or 'auto'
palette="blue", # 'zinc', 'slate', 'blue', 'violet', 'green', 'rose', 'orange'
# Custom Tailwind extensions
tailwind_config={
"theme": {
"extend": {
"colors": {
"brand": "#0ea5e9",
"accent-glow": "#38bdf8"
},
"fontFamily": {
"mono": ["Fira Code", "monospace"]
}
}
}
},
# Custom Google Fonts or external CSS
stylesheets=[
"https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;600&display=swap"
],
# External JavaScript CDN libraries (e.g. Canvas Confetti, Lucide)
scripts=[
"https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js"
],
# Custom global CSS rules
custom_css="""
body { font-family: 'Inter', sans-serif; }
code, pre { font-family: 'Fira Code', monospace; }
""",
# Custom <head> tags (e.g. meta tags, OpenGraph, favicon)
head="""
<meta name="description" content="Production Analytics Portal powered by PyDataUI">
<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🚀</text></svg>">
"""
)
7. Creating Reusable Custom Components
You can encapsulate your own custom UI design system components by subclassing Component:
from pydataui import Component
class GlassCard(Component):
"""Reusable Glassmorphism Card with Tailwind CSS."""
tag = "div"
def _get_classes(self):
return [
"backdrop-blur-xl bg-card/60 border border-border/50",
"rounded-2xl p-6 shadow-xl hover:shadow-2xl transition-all duration-300"
]
# Usage:
card = GlassCard(
H2("Custom Glass Component", class_name="text-lg font-bold"),
P("Encapsulated styling that can be reused across pages.")
)
Custom Glass Component
Encapsulated styling with blur and glowing border that can be reused across pages.
8. Advanced Animations with GSAP (GreenSock)
PyDataUI has zero limitations on client-side animation and script libraries. You can integrate GSAP (GreenSock), ScrollTrigger, Anime.js, Lucide Icons, Canvas Confetti, and Three.js with full reactive state support.
Loading GSAP in App
Pass the official GSAP CDN links directly to the scripts parameter:
from pydataui import App
app = App(
title="GSAP Animated App",
theme="dark",
palette="zinc",
scripts=[
"https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js",
"https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js",
]
)
Staggered Entrance & Micro-Interactions
Attach standard CSS classes (gsap-hero, gsap-card) to any PyDataUI or shadcn component, and embed your animation logic using Html:
from pydataui.html import Div, H1, P, Html
from pydataui.shadcn import ShadCard, ShadButton
@app.page("/")
def home():
return Div(
H1("Fluid Animations", class_name="gsap-hero text-5xl font-extrabold tracking-tight"),
P("60fps physics-based motion with zero configuration.", class_name="gsap-hero text-muted-foreground mt-2"),
Div(
ShadCard(H3("Card 1"), class_name="gsap-card p-6"),
ShadCard(H3("Card 2"), class_name="gsap-card p-6"),
ShadCard(H3("Card 3"), class_name="gsap-card p-6"),
class_name="grid grid-cols-3 gap-6 mt-8"
),
# Embedded GSAP Script
Html("""
<script>
function runAnimations() {
// Staggered hero text entrance
gsap.from(".gsap-hero", {
y: -30,
opacity: 0,
duration: 0.9,
stagger: 0.15,
ease: "power4.out"
});
// Spring entrance for cards
gsap.from(".gsap-card", {
scale: 0.88,
opacity: 0,
duration: 0.8,
delay: 0.3,
stagger: 0.18,
ease: "back.out(1.7)"
});
}
// Execute on initial page load
document.addEventListener("DOMContentLoaded", runAnimations);
// Re-trigger after HTMX partial page swaps (reactive updates)
document.addEventListener("htmx:afterSwap", runAnimations);
</script>
"""),
class_name="min-h-screen p-12 bg-background text-foreground"
)
Coordinating GSAP with Reactive Server State (HTMX)
When Python updates state on the server (e.g. via HTMX swaps), simply listen to htmx:afterSwap or htmx:afterSettle:
- Initial render: DOMContentLoaded runs the entrance timeline.
- Dynamic data refresh: htmx:afterSwap animates updated numbers, flash badges, or newly inserted list rows.
9. Working Example
See the full working showcase in examples/custom_ui_app.py: