Skip to content

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")
Supported sizes: size="default", size="sm", size="lg", size="icon".

Rendered UI Preview

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"
)
Rendered UI Preview

Model Deployment

Manage endpoint scaling and compute clusters.

v1.1.1
Current status: Healthy across 3 replicas (sub-15ms latency).

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")
Rendered UI Preview
Target Database
Enable Query Cache
Environment: Production 99.9% SLI

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")
        ]
    )
Rendered UI Preview (Collapsible Sidebar & Shell)
⚡
PyDataUI Platform ENT
Platform
📦Model Registry14
✨Prompt Studio
📈Telemetry & Drift
UI
PyDataUI Admin admin@pydataui.org
Home/Models/Mistral-7B
Search actions...⌘K
Inference Latency
14.2 ms
↓ -3.1 ms optimal

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"},
    ]
)
Rendered UI Preview (Dropdown & Tooltip)
📊 View Metrics⌘M
📦 Clone Config
🗑️ Delete Cluster
GPU Cluster Online (8x H100)

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)
Rendered UI Preview (Slider & Radio Cards)
Sampling Temperature 0.70
vLLM Engine FAST

High-speed PagedAttention inference server

HuggingFace TGI

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
Use it immediately in pure Python:
from components.shadcn.carousel import Carousel

Carousel(items=[Card(...), Card(...)])

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.")
)
Rendered UI Preview (Glassmorphism)

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:

python examples/custom_ui_app.py
Open http://127.0.0.1:8080 to inspect the dark theme, violet palette, interactive progress bars, and custom SVG animations.