API Reference

animaid

Animaid - Create beautiful HTML from Python data structures.

Quick Start:

>>> from animaid import HTMLString, HTMLList, HTMLDict

# Styled text - chain methods for easy styling >>> HTMLString(“Hello”).bold().red().render() ‘<span style=”font-weight: bold; color: red”>Hello</span>’

# Styled lists - use presets for common patterns >>> HTMLList([“Apple”, “Banana”, “Cherry”]).pills().render()

# Styled dicts - display key-value data beautifully >>> HTMLDict({“name”: “Alice”, “age”: 30}).card().render()

Beginner Tips:

• Use method shortcuts: .bold(), .red(), .large() instead of .styled(…)

• Use presets: .cards(), .pills(), .badge(), .highlight() for common styles

• Chain methods: HTMLString(“Hi”).bold().red().large()

• Methods modify in-place and return self for chaining

class animaid.AlignContent(value)

Bases: Enum

CSS align-content values for multi-line flex/grid containers.

CENTER = 'center'

END = 'end'

SPACE_AROUND = 'space-around'

SPACE_BETWEEN = 'space-between'

SPACE_EVENLY = 'space-evenly'

START = 'start'

STRETCH = 'stretch'

to_css() → str

class animaid.AlignItems(value)

Bases: Enum

CSS align-items values.

BASELINE = 'baseline'

CENTER = 'center'

END = 'end'

FLEX_END = 'flex-end'

FLEX_START = 'flex-start'

START = 'start'

STRETCH = 'stretch'

to_css() → str

class animaid.App(port: int = 8200, title: str = 'AnimAID', auto_open: bool = True, window: WindowConfig | None = None, width: int | None = None, height: int | None = None, theme: str = 'light')

Bases: object

A Tkinter-like interactive GUI environment using HTML.

The browser becomes the display surface, and AnimAID objects become widgets that can be added, updated, and removed programmatically with real-time visual feedback.

Examples

>>> from animaid import App, HTMLString
>>> app = App()
>>> app.run()  # Starts server, opens browser
>>> app.add(HTMLString("Hello").bold)
'string_1'
>>> app.add(HTMLString("World").italic)
'string_2'
>>> app.stop()

# Context manager support >>> with App() as app: … app.add(HTMLString(“Temporary display”)) # Server stops when context exits

# With window configuration >>> with App(title=”Dashboard”, theme=”dark”) as app: … app.window.set_title(“Loading…”) … app.add(HTMLString(“Content”))

Note

The class was previously named Animate. That name still works but is deprecated. Please use App instead.

add(item: HTMLObject | str, id: str | None = None) → str

Add an item to the display.

Parameters:

• item – An HTMLObject or string to display.

• id – Optional custom ID for the item. Auto-generated if not provided.

Returns:

The ID of the added item.

clear(item_or_id: HTMLObject | str) → bool

Remove an item by ID or by object reference.

Parameters:

item_or_id – The ID of the item to remove, or the item object itself.

Returns:

True if the item was found and removed, False otherwise.

clear_all() → None

Remove all items from the display.

get(id: str) → Any

Get an item by ID.

Parameters:

id – The ID of the item to retrieve.

Returns:

The item if found, None otherwise.

get_events() → list[InputEvent]

Get all pending events without blocking.

Returns:

A list of all pending InputEvent objects. Empty list if none.

Examples

>>> events = anim.get_events()
>>> for event in events:
...     print(f"Event: {event.event_type} on {event.id}")

get_full_state() → list[dict[str, str]]

Get the full state as a list of rendered items.

Returns:

…, “html”: …} dicts.

Return type:

A list of {“id”

handle_input_event(message: dict[str, Any]) → None

Handle an input event from the browser.

This is called by the server when an input event is received. It updates the item’s internal value, calls registered callbacks, and queues the event for polling.

Parameters:

message – The event message containing id, event type, and value.

handle_window_event(message: dict[str, Any]) → None

Handle a window event from the browser.

This is called by the server when a window event is received.

Parameters:

message – The event message containing event type and data.

property is_running: bool

Check if the server is running.

items() → list[tuple[str, Any]]

Get a copy of all items.

Returns:

A list of (id, item) tuples.

property port: int

Get the server port.

refresh(id: str) → bool

Re-render and broadcast a single item.

Use this to manually refresh an item after external changes.

Parameters:

id – The ID of the item to refresh.

Returns:

True if item was found and refreshed, False otherwise.

refresh_all() → None

Re-render and broadcast all items.

Use this to manually refresh all items after external changes.

register_connection(websocket: Any) → None

Register a WebSocket connection.

This is called by the server when a new client connects.

Parameters:

websocket – The WebSocket connection to register.

remove(item_or_id: HTMLObject | str) → bool

Remove an item by ID or by object reference.

Parameters:

item_or_id – The ID of the item to remove, or the item object itself.

Returns:

True if the item was found and removed, False otherwise.

run() → App

Start the server in a background thread and open the browser.

Returns:

Self for method chaining.

stop() → None

Stop the server.

property title: str

Get the display title.

unregister_connection(websocket: Any) → None

Unregister a WebSocket connection.

This is called by the server when a client disconnects.

Parameters:

websocket – The WebSocket connection to unregister.

update(id: str, item: HTMLObject | str) → bool

Update an existing item by ID.

Parameters:

• id – The ID of the item to update.

• item – The new content to display.

Returns:

True if the item was found and updated, False otherwise.

property url: str

Get the server URL.

wait_for_event(timeout: float | None = None) → InputEvent | None

Block until an input event occurs.

Parameters:

timeout – Maximum time to wait in seconds. None means wait forever.

Returns:

The InputEvent if one occurred, None if timeout expired.

Examples

>>> event = anim.wait_for_event(timeout=1.0)
>>> if event and event.event_type == "click":
...     print(f"Button {event.id} was clicked!")

property window: Window

Access window-level controls.

Returns:

The Window instance for controlling window appearance and behavior.

Examples

>>> app.window.dark()  # Switch to dark theme
>>> app.window.set_title("Processing...")

class animaid.Border(width: Size | str | int | float = '1px', style: BorderStyle | str = BorderStyle.SOLID, color: Color | str = 'black')

Bases: CSSValue

Represents a CSS border value (width + style + color).

Examples

>>> Border(Size.px(1), BorderStyle.SOLID, Color.black)
Border('1px solid black')
>>> Border.solid(2, "red")
Border('2px solid red')
>>> Border().width(Size.px(2)).dashed().color(Color.blue)
Border('2px dashed blue')

as_dashed() → Border

Return a new Border with dashed style.

as_dotted() → Border

Return a new Border with dotted style.

as_double() → Border

Return a new Border with double style.

as_none() → Border

Return a new Border with no style.

as_solid() → Border

Return a new Border with solid style.

color(c: Color | str) → Border

Return a new Border with the specified color.

property color_value: Color

The border color.

classmethod dashed(width: Size | str | int | float = 1, color: Color | str = 'black') → Border

Create a dashed border.

Parameters:

• width – Border width (default 1px)

• color – Border color (default black)

Examples

>>> Border.dashed()
Border('1px dashed black')
>>> Border.dashed(2, "blue")
Border('2px dashed blue')

classmethod dotted(width: Size | str | int | float = 1, color: Color | str = 'black') → Border

Create a dotted border.

Parameters:

• width – Border width (default 1px)

• color – Border color (default black)

Examples

>>> Border.dotted()
Border('1px dotted black')

classmethod double(width: Size | str | int | float = 3, color: Color | str = 'black') → Border

Create a double border.

Parameters:

• width – Border width (default 3px - minimum for double to show)

• color – Border color (default black)

Examples

>>> Border.double()
Border('3px double black')

classmethod medium(color: Color | str = 'black', style: BorderStyle | str = BorderStyle.SOLID) → Border

Create a medium border (2px).

Parameters:

• color – Border color (default black)

• style – Border style (default solid)

Examples

>>> Border.medium()
Border('2px solid black')

classmethod none() → Border

Create a border with no visible style.

Examples

>>> Border.none()
Border('1px none black')

classmethod solid(width: Size | str | int | float = 1, color: Color | str = 'black') → Border

Create a solid border.

Parameters:

• width – Border width (default 1px)

• color – Border color (default black)

Examples

>>> Border.solid()
Border('1px solid black')
>>> Border.solid(2, "red")
Border('2px solid red')

style(s: BorderStyle | str) → Border

Return a new Border with the specified style.

property style_value: BorderStyle

The border style.

classmethod thick(color: Color | str = 'black', style: BorderStyle | str = BorderStyle.SOLID) → Border

Create a thick border (4px).

Parameters:

• color – Border color (default black)

• style – Border style (default solid)

Examples

>>> Border.thick()
Border('4px solid black')
>>> Border.thick("navy")
Border('4px solid navy')

classmethod thin(color: Color | str = 'black', style: BorderStyle | str = BorderStyle.SOLID) → Border

Create a thin border (1px).

Parameters:

• color – Border color (default black)

• style – Border style (default solid)

Examples

>>> Border.thin()
Border('1px solid black')
>>> Border.thin("red")
Border('1px solid red')

to_css() → str

Return the CSS border shorthand.

width(w: Size | str | int | float) → Border

Return a new Border with the specified width.

property width_value: Size

The border width.

class animaid.BorderStyle(value)

Bases: Enum

CSS border-style values.

DASHED = 'dashed'

DOTTED = 'dotted'

DOUBLE = 'double'

GROOVE = 'groove'

HIDDEN = 'hidden'

INSET = 'inset'

NONE = 'none'

OUTSET = 'outset'

RIDGE = 'ridge'

SOLID = 'solid'

to_css() → str

animaid.Button

alias of HTMLButton

class animaid.CSSValue

Bases: ABC

Base class for all CSS value types.

All CSS value classes must implement to_css() which returns the CSS string representation. They also support str() conversion for backward compatibility.

abstractmethod to_css() → str

Return the CSS string representation of this value.

animaid.Card

alias of HTMLCard

animaid.Checkbox

alias of HTMLCheckbox

class animaid.Color(value: str)

Bases: CSSValue

Represents a CSS color value.

Supports named colors, hex codes, rgb(), rgba(), hsl(), and hsla().

Examples

>>> Color.red
Color('red')
>>> Color.hex("#2563eb")
Color('#2563eb')
>>> Color.rgb(255, 128, 0)
Color('rgb(255, 128, 0)')
>>> Color.rgba(255, 128, 0, 0.5)
Color('rgba(255, 128, 0, 0.5)')

NAMED_COLORS: ClassVar[set[str]] = {'aqua', 'black', 'blue', 'brown', 'currentcolor', 'cyan', 'fuchsia', 'gray', 'green', 'grey', 'inherit', 'initial', 'lime', 'magenta', 'maroon', 'navy', 'olive', 'orange', 'pink', 'purple', 'red', 'silver', 'teal', 'transparent', 'unset', 'white', 'yellow'}

aqua: ClassVar[Color] = Color('aqua')

black: ClassVar[Color] = Color('black')

blue: ClassVar[Color] = Color('blue')

brown: ClassVar[Color] = Color('brown')

cyan: ClassVar[Color] = Color('cyan')

dark_gray: ClassVar[Color] = Color('#374151')

error: ClassVar[Color] = Color('#ef4444')

gray: ClassVar[Color] = Color('gray')

green: ClassVar[Color] = Color('green')

grey: ClassVar[Color] = Color('grey')

classmethod hex(code: str) → Color

Create a color from a hex code.

Parameters:

code – Hex code with or without ‘#’ prefix

classmethod hsl(h: int, s: int, lightness: int) → Color

Create an HSL color.

Parameters:

• h – Hue (0-360)

• s – Saturation (0-100)

• lightness – Lightness (0-100)

classmethod hsla(h: int, s: int, lightness: int, a: float) → Color

Create an HSLA color with alpha.

Parameters:

• h – Hue (0-360)

• s – Saturation (0-100)

• lightness – Lightness (0-100)

• a – Alpha (0.0-1.0)

info: ClassVar[Color] = Color('#3b82f6')

light_gray: ClassVar[Color] = Color('#f5f5f5')

lime: ClassVar[Color] = Color('lime')

magenta: ClassVar[Color] = Color('magenta')

maroon: ClassVar[Color] = Color('maroon')

muted: ClassVar[Color] = Color('#6b7280')

navy: ClassVar[Color] = Color('navy')

olive: ClassVar[Color] = Color('olive')

orange: ClassVar[Color] = Color('orange')

pink: ClassVar[Color] = Color('pink')

purple: ClassVar[Color] = Color('purple')

red: ClassVar[Color] = Color('red')

classmethod rgb(r: int, g: int, b: int) → Color

Create an RGB color.

Parameters:

• r – Red component (0-255)

• g – Green component (0-255)

• b – Blue component (0-255)

classmethod rgba(r: int, g: int, b: int, a: float) → Color

Create an RGBA color with alpha.

Parameters:

• r – Red component (0-255)

• g – Green component (0-255)

• b – Blue component (0-255)

• a – Alpha component (0.0-1.0)

silver: ClassVar[Color] = Color('silver')

success: ClassVar[Color] = Color('#22c55e')

teal: ClassVar[Color] = Color('teal')

to_css() → str

Return the CSS string representation.

transparent: ClassVar[Color] = Color('transparent')

warning: ClassVar[Color] = Color('#f59e0b')

white: ClassVar[Color] = Color('white')

yellow: ClassVar[Color] = Color('yellow')

animaid.Column

alias of HTMLColumn

animaid.Container

alias of HTMLContainer

animaid.Dict

alias of HTMLDict

class animaid.Display(value)

Bases: Enum

CSS display values.

BLOCK = 'block'

CONTENTS = 'contents'

FLEX = 'flex'

GRID = 'grid'

INLINE = 'inline'

INLINE_BLOCK = 'inline-block'

INLINE_FLEX = 'inline-flex'

INLINE_GRID = 'inline-grid'

NONE = 'none'

to_css() → str

animaid.Divider

alias of HTMLDivider

class animaid.DividerStyle(value)

Bases: Enum

Divider line styles (maps to border-style).

DASHED = 'dashed'

DOTTED = 'dotted'

DOUBLE = 'double'

SOLID = 'solid'

to_css() → str

class animaid.FlexDirection(value)

Bases: Enum

CSS flex-direction values.

COLUMN = 'column'

COLUMN_REVERSE = 'column-reverse'

ROW = 'row'

ROW_REVERSE = 'row-reverse'

to_css() → str

class animaid.FlexWrap(value)

Bases: Enum

CSS flex-wrap values.

NOWRAP = 'nowrap'

WRAP = 'wrap'

WRAP_REVERSE = 'wrap-reverse'

to_css() → str

animaid.Float

alias of HTMLFloat

class animaid.FontStyle(value)

Bases: Enum

CSS font-style values.

ITALIC = 'italic'

NORMAL = 'normal'

OBLIQUE = 'oblique'

to_css() → str

class animaid.FontWeight(value)

Bases: Enum

CSS font-weight values.

BOLD = 'bold'

BOLDER = 'bolder'

LIGHTER = 'lighter'

NORMAL = 'normal'

W100 = '100'

W200 = '200'

W300 = '300'

W400 = '400'

W500 = '500'

W600 = '600'

W700 = '700'

W800 = '800'

W900 = '900'

to_css() → str

Return the CSS value.

class animaid.GridAutoFlow(value)

Bases: Enum

CSS grid-auto-flow values.

COLUMN = 'column'

COLUMN_DENSE = 'column dense'

ROW = 'row'

ROW_DENSE = 'row dense'

to_css() → str

class animaid.HTMLButton(label: str)

Bases: object

A clickable button widget for use with App.

Buttons support click callbacks and styled presets for common use cases.

Examples

>>> button = HTMLButton("Click Me")
>>> button = HTMLButton("Submit").primary()
>>> button = HTMLButton("Delete").danger().on_click(handle_delete)

# With App >>> with App() as app: … def on_click(): … print(“Button clicked!”) … app.add(HTMLButton(“Click”).on_click(on_click))

add_class(*class_names: str) → HTMLButton

Return a copy with additional CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

A new instance with the additional classes.

danger() → HTMLButton

Return a copy styled as a danger button (red).

Returns:

A new instance with danger styling.

property label: str

Get the button label.

large() → HTMLButton

Return a copy styled with larger text and padding.

Returns:

A new instance with large styling.

on_click(callback: Callable[[], None]) → HTMLButton

Register a callback for button clicks.

The callback is called whenever the button is clicked in the browser. The callback takes no arguments.

Parameters:

callback – A function to call when the button is clicked.

Returns:

Self for method chaining.

Examples

>>> def handle_click():
...     print("Button was clicked!")
>>> button = HTMLButton("Click Me").on_click(handle_click)

primary() → HTMLButton

Return a copy styled as a primary button (blue).

Returns:

A new instance with primary styling.

render() → str

Return HTML representation of this button.

Returns:

A string containing valid HTML for the button.

small() → HTMLButton

Return a copy styled with smaller text and padding.

Returns:

A new instance with small styling.

styled(**styles: str) → HTMLButton

Return a copy with additional inline styles.

Style names use Python convention (underscores) and are converted to CSS convention (hyphens) automatically.

Parameters:

**styles – CSS property-value pairs, e.g., font_size=”16px”

Returns:

A new instance with the combined styles.

success() → HTMLButton

Return a copy styled as a success button (green).

Returns:

A new instance with success styling.

warning() → HTMLButton

Return a copy styled as a warning button (orange).

Returns:

A new instance with warning styling.

class animaid.HTMLCard(children: list[Any] | None = None, *, title: str | None = None, **styles: str | CSSValue)

Bases: HTMLContainer

A visual card container for grouping related content.

HTMLCard provides a bordered/shadowed container with optional title, commonly used for dashboard panels, info cards, and grouped content.

Examples

>>> from animaid import HTMLCard, HTMLString
>>> card = HTMLCard([
...     HTMLString("User Profile").bold(),
...     HTMLString("Name: Alice"),
... ])

>>> # Card with title
>>> card = HTMLCard(
...     title="User Profile",
...     children=[HTMLString("Name: Alice")],
... )

>>> # Styled card
>>> card = HTMLCard(content).shadow().rounded()
>>> card = HTMLCard(content).elevated()  # Preset with larger shadow

add_class(*class_names: str) → HTMLCard

Add CSS classes.

background(color: Color | str) → HTMLCard

Set the background color.

Parameters:

color – Background color.

Returns:

Self for method chaining.

bordered(color: Color | str = '#e5e7eb') → HTMLCard

Add a border to the card.

Parameters:

color – Border color.

Returns:

Self for method chaining.

default() → HTMLCard

Apply default card styling (light border, subtle shadow).

Returns:

Self for method chaining.

elevated() → HTMLCard

Apply elevated card styling (prominent shadow).

Returns:

Self for method chaining.

filled(color: Color | str = '#f9fafb') → HTMLCard

Apply filled card styling with background color.

Parameters:

color – Background color.

Returns:

Self for method chaining.

flat() → HTMLCard

Apply flat card styling (no border or shadow).

Returns:

Self for method chaining.

gap(size: Size | str | int) → HTMLCard

Set the gap between child elements.

height(size: Size | str | int) → HTMLCard

Set container height.

margin(size: Spacing | Size | str | int) → HTMLCard

Set external margin.

max_width(size: Size | str | int) → HTMLCard

Set maximum container width.

min_width(size: Size | str | int) → HTMLCard

Set minimum container width.

no_border() → HTMLCard

Remove the border.

Returns:

Self for method chaining.

no_rounded() → HTMLCard

Remove border radius (sharp corners).

Returns:

Self for method chaining.

no_shadow() → HTMLCard

Remove the box shadow.

Returns:

Self for method chaining.

outlined() → HTMLCard

Apply outlined card styling (border only, no shadow).

Returns:

Self for method chaining.

padding(size: Spacing | Size | str | int) → HTMLCard

Set internal padding.

render() → str

Render the card with optional title.

Returns:

HTML string with card structure.

rounded(size: RadiusSize | str = RadiusSize.DEFAULT) → HTMLCard

Set the border radius (rounded corners).

Parameters:

size – RadiusSize enum or CSS radius string.

Returns:

Self for method chaining.

Example

>>> card.rounded()  # Default rounding
>>> card.rounded(RadiusSize.LG)  # More rounded

set_title(text: str | None) → HTMLCard

Set or change the card title.

Parameters:

text – Title text, or None to remove title.

Returns:

Self for method chaining.

shadow(size: ShadowSize | str = ShadowSize.DEFAULT) → HTMLCard

Add a box shadow to the card.

Parameters:

size – ShadowSize enum or CSS shadow string.

Returns:

Self for method chaining.

Example

>>> card.shadow()  # Default shadow
>>> card.shadow(ShadowSize.LG)  # Larger shadow

styled(**styles: str | CSSValue) → HTMLCard

Apply additional inline styles.

property title: str | None

Get the card title.

width(size: Size | str | int) → HTMLCard

Set container width.

class animaid.HTMLCheckbox(label: str, checked: bool = False)

Bases: object

A checkbox widget with two-way boolean binding.

The checked property is automatically synced from the browser when the user toggles the checkbox.

Examples

>>> checkbox = HTMLCheckbox("Accept terms", checked=False)
>>> checkbox = HTMLCheckbox("Enable feature").on_change(handle_change)

# With App - two-way binding >>> with App() as app: … terms = HTMLCheckbox(“I accept the terms”) … app.add(terms) … # Later, read the current value: … print(terms.checked) # True/False synced from browser

add_class(*class_names: str) → HTMLCheckbox

Return a copy with additional CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

A new instance with the additional classes.

property checked: bool

Get the current checked state (thread-safe).

The value is automatically synced from the browser when the user toggles the checkbox.

Returns:

True if checked, False otherwise.

property label: str

Get the checkbox label.

large() → HTMLCheckbox

Return a copy with larger text and checkbox.

Returns:

A new instance with large styling.

on_change(callback: Callable[[bool], None]) → HTMLCheckbox

Register a callback for state changes.

The callback is called when the user toggles the checkbox.

Parameters:

callback – A function that takes the new checked state as argument.

Returns:

Self for method chaining.

Examples

>>> def handle_change(checked):
...     print(f"Checkbox is now: {'checked' if checked else 'unchecked'}")
>>> checkbox = HTMLCheckbox("Enable").on_change(handle_change)

render() → str

Return HTML representation of this checkbox.

Returns:

A string containing valid HTML for the checkbox.

small() → HTMLCheckbox

Return a copy with smaller text and checkbox.

Returns:

A new instance with small styling.

styled(**styles: str) → HTMLCheckbox

Return a copy with additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

A new instance with the combined styles.

property value: bool

Alias for checked property (for HTMLInput compatibility).

class animaid.HTMLColumn(children: list[Any] | None = None, **styles: str | CSSValue)

Bases: HTMLContainer

A vertical flex container for arranging items in a column.

HTMLColumn uses CSS flexbox with flex-direction: column to arrange children vertically. It provides methods for controlling alignment, justification, and spacing.

Examples

>>> from animaid import HTMLColumn, HTMLString
>>> column = HTMLColumn([
...     HTMLString("Title").bold().xl(),
...     HTMLString("Subtitle").muted(),
...     HTMLString("Content here..."),
... ]).gap(8)

>>> # Form-style layout
>>> column = HTMLColumn(form_fields).form()

>>> # Stacked layout with consistent spacing
>>> column = HTMLColumn(items).stack()

add_class(*class_names: str) → HTMLColumn

Add CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

align(value: AlignItems | str) → HTMLColumn

Set horizontal alignment of items within the column.

Parameters:

value – AlignItems enum or CSS string (start, center, end, stretch, baseline).

Returns:

Self for method chaining.

Example

>>> column.align(AlignItems.CENTER)
>>> column.align("center")  # Also works

centered() → HTMLColumn

Center all items both horizontally and vertically.

Returns:

Self for method chaining.

end() → HTMLColumn

Align items to the end (bottom).

Returns:

Self for method chaining.

form() → HTMLColumn

Apply form-style layout preset.

Creates a column with appropriate spacing for form fields and full-width stretching.

Returns:

Self for method chaining.

gap(size: Size | str | int) → HTMLColumn

Set the gap between child elements.

Parameters:

size – Gap size.

Returns:

Self for method chaining.

height(size: Size | str | int) → HTMLColumn

Set container height.

Parameters:

size – Height.

Returns:

Self for method chaining.

justify(value: JustifyContent | str) → HTMLColumn

Set vertical distribution of items within the column.

Parameters:

value – JustifyContent enum or CSS string (start, center, end, space-between, space-around, space-evenly).

Returns:

Self for method chaining.

Example

>>> column.justify(JustifyContent.SPACE_BETWEEN)
>>> column.justify("space-between")  # Also works

margin(size: Spacing | Size | str | int) → HTMLColumn

Set external margin.

Parameters:

size – Margin size.

Returns:

Self for method chaining.

padding(size: Spacing | Size | str | int) → HTMLColumn

Set internal padding.

Parameters:

size – Padding size.

Returns:

Self for method chaining.

reverse() → HTMLColumn

Reverse the order of items (bottom to top).

Returns:

Self for method chaining.

spaced() → HTMLColumn

Distribute items with space between them.

Returns:

Self for method chaining.

stack() → HTMLColumn

Apply simple stacked layout preset.

Creates a column with consistent 8px gap between items.

Returns:

Self for method chaining.

start() → HTMLColumn

Align items to the start (top).

Returns:

Self for method chaining.

stretch() → HTMLColumn

Stretch items to fill the column width.

Returns:

Self for method chaining.

styled(**styles: str | CSSValue) → HTMLColumn

Apply additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

Self for method chaining.

width(size: Size | str | int) → HTMLColumn

Set container width.

Parameters:

size – Width.

Returns:

Self for method chaining.

wrap(value: FlexWrap | str = FlexWrap.WRAP) → HTMLColumn

Allow items to wrap to the next column (rarely used).

Parameters:

value – FlexWrap enum or CSS string.

Returns:

Self for method chaining.

class animaid.HTMLContainer(children: list[Any] | None = None, **styles: str | CSSValue)

Bases: HTMLObject

Base class for all container widgets.

Containers hold child elements and provide layout capabilities. They can be nested and support reactive updates when children change.

Example

>>> container = HTMLContainer([HTMLString("Hello"), HTMLString("World")])
>>> container.render()
'<div>...</div>'

add_class(*class_names: str) → HTMLContainer

Add CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

append(child: Any) → HTMLContainer

Add a child element and trigger update.

Parameters:

child – The element to add.

Returns:

Self for method chaining.

property children: list[Any]

Get the list of children (read-only copy).

clear() → HTMLContainer

Remove all children.

Returns:

Self for method chaining.

expand() → HTMLContainer

Make this container expand to fill available space in a flex parent.

Use this on a child container to make it grow and fill remaining space.

Returns:

Self for method chaining.

Example

>>> # Header, expandable content, footer layout
>>> layout = HTMLColumn([
...     HTMLString("Header"),
...     HTMLColumn([HTMLString("Content")]).expand(),
...     HTMLString("Footer"),
... ]).full_height()

extend(children: list[Any]) → HTMLContainer

Add multiple child elements.

Parameters:

children – List of elements to add.

Returns:

Self for method chaining.

full_height() → HTMLContainer

Expand container to fill the full viewport height.

Returns:

Self for method chaining.

Example

>>> column = HTMLColumn([...]).full_height()

full_screen() → HTMLContainer

Expand container to fill the entire viewport (width and height).

Returns:

Self for method chaining.

Example

>>> layout = HTMLColumn([...]).full_screen()

full_width() → HTMLContainer

Expand container to fill the full width of its parent.

Returns:

Self for method chaining.

Example

>>> row = HTMLRow([...]).full_width()

gap(size: Size | str | int) → HTMLContainer

Set the gap between child elements.

Parameters:

size – Gap size (Size, CSS string like “10px”, or int pixels).

Returns:

Self for method chaining.

height(size: Size | str | int) → HTMLContainer

Set container height.

Parameters:

size – Height (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

insert(index: int, child: Any) → HTMLContainer

Insert a child at a specific position.

Parameters:

• index – Position to insert at.

• child – The element to insert.

Returns:

Self for method chaining.

margin(size: Spacing | Size | str | int) → HTMLContainer

Set external margin.

Parameters:

size – Margin size (Spacing, Size, CSS string, or int pixels).

Returns:

Self for method chaining.

max_height(size: Size | str | int) → HTMLContainer

Set maximum container height.

Parameters:

size – Maximum height (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

max_width(size: Size | str | int) → HTMLContainer

Set maximum container width.

Parameters:

size – Maximum width (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

min_height(size: Size | str | int) → HTMLContainer

Set minimum container height.

Parameters:

size – Minimum height (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

min_width(size: Size | str | int) → HTMLContainer

Set minimum container width.

Parameters:

size – Minimum width (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

padding(size: Spacing | Size | str | int) → HTMLContainer

Set internal padding.

Parameters:

size – Padding size (Spacing, Size, CSS string, or int pixels).

Returns:

Self for method chaining.

pop(index: int = -1) → Any

Remove and return a child at the given position.

Parameters:

index – Position to remove from (default: last).

Returns:

The removed child element.

remove(child: Any) → HTMLContainer

Remove a child element.

Parameters:

child – The element to remove.

Returns:

Self for method chaining.

remove_class(*class_names: str) → HTMLContainer

Remove CSS classes.

Parameters:

*class_names – CSS class names to remove.

Returns:

Self for method chaining.

render() → str

Render the container and all children.

Returns:

HTML string with container div and rendered children.

styled(**styles: str | CSSValue) → HTMLContainer

Apply additional inline styles.

Parameters:

**styles – CSS property-value pairs (underscores become hyphens).

Returns:

Self for method chaining.

width(size: Size | str | int) → HTMLContainer

Set container width.

Parameters:

size – Width (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

class animaid.HTMLDict(data: dict[Any, Any] | None = None, **styles: str | CSSValue)

Bases: HTMLObject, dict

A dict subclass that renders as styled HTML.

HTMLDict behaves like a regular Python dict but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining. Supports definition list, table, and flexbox layouts.

Examples

>>> d = HTMLDict({"name": "Alice", "age": 30})
>>> d.render()
'<dl><dt>name</dt><dd>Alice</dd><dt>age</dt><dd>30</dd></dl>'

>>> d.as_table().render()
'<table><tr><td>name</td><td>Alice</td></tr>...</table>'

>>> d.key_bold().key_color("blue").render()
'<dl><dt style="font-weight: bold; color: blue">name</dt>...'

add_class(*class_names: str) → Self

Add CSS classes on the container in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

add_key_class(*class_names: str) → Self

Add CSS classes to keys in-place.

Parameters:

*class_names – CSS class names to add to keys.

add_value_class(*class_names: str) → Self

Add CSS classes to values in-place.

Parameters:

*class_names – CSS class names to add to values.

as_definition_list() → Self

Apply definition list (<dl>) format in-place.

as_divs() → Self

Apply flexbox divs format in-place.

as_table() → Self

Apply table (<table>) format in-place.

background(value: Color | str) → Self

Apply container background in-place.

Parameters:

value – CSS color value (e.g., “white”, Color.white, Color.hex(“#fff”)).

border(value: Border | str) → Self

Apply container border in-place.

Parameters:

value – CSS border value (e.g., “1px solid black”, Border.solid()).

border_radius(value: Size | str | int | float) → Self

Apply rounded container corners in-place.

Parameters:

value – CSS border-radius value (e.g., “5px”, Size.px(5), Size.percent(50)).

bordered() → Self

Apply bordered cells style in-place.

Each key-value pair has visible borders.

card() → Self

Apply card style with shadow and rounded corners in-place.

Creates a visually appealing card-style display.

clear() → None

Clear dict, notifying observers.

color(value: Color | str) → Self

Apply text color in-place.

Parameters:

value – CSS color value (e.g., “black”, Color.black).

compact() → Self

Apply compact spacing style in-place.

Minimal padding and spacing for dense displays.

entry_separator(value: Border | str) → Self

Apply separator between entries (border) in-place.

Parameters:

value – CSS border value for separator (e.g., “1px solid gray”).

gap(value: Size | str | int | float) → Self

Apply gap between entries in-place.

Parameters:

value – CSS gap value (e.g., “10px”, Size.px(10), Size.rem(1)).

grid(columns: int = 2) → Self

Apply grid layout in-place.

Parameters:

columns – Number of key-value pairs per row.

hide_keys() → Self

Hide keys and only render values in-place.

horizontal() → Self

Apply horizontal layout (entries side by side) in-place.

inline() → Self

Apply inline horizontal display in-place.

All key-value pairs on one line.

key_background(value: Color | str) → Self

Apply background color to keys in-place.

Parameters:

value – CSS color value (e.g., “yellow”, Color.yellow).

key_bold() → Self

Apply bold style to keys in-place.

key_color(value: Color | str) → Self

Apply color to keys in-place.

Parameters:

value – CSS color value (e.g., “blue”, Color.blue, Color.hex(“#00f”)).

key_italic() → Self

Apply italic style to keys in-place.

key_padding(value: Spacing | str | int | float) → Self

Apply padding to keys in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10), Spacing.all(10)).

key_styled(**styles: str | CSSValue) → Self

Apply styles to keys in-place.

Parameters:

**styles – CSS property-value pairs for keys. Accepts both strings and CSS type objects (Color, Size, etc.)

key_width(value: Size | str | int | float) → Self

Apply fixed key width in-place.

Parameters:

value – CSS width value (e.g., “100px”, Size.px(100)).

labeled() → Self

Apply label-style keys in-place.

Keys are styled as small labels above values.

margin(value: Spacing | str | int | float) → Self

Apply container margin in-place.

Parameters:

value – CSS margin value (e.g., “10px”, Size.px(10), Spacing.all(10)).

max_width(value: Size | str | int | float) → Self

Apply maximum width in-place.

Parameters:

value – CSS max-width value (e.g., “500px”, Size.px(500), Size.vw(80)).

padding(value: Spacing | str | int | float) → Self

Apply container padding in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10)).

pop(key: Any, *default: Any) → Any

Pop item, notifying observers.

popitem() → tuple[Any, Any]

Pop item, notifying observers.

render() → str

Return HTML representation of this dictionary.

Returns:

A string containing valid HTML.

separator(value: str) → Self

Apply a separator between key and value in-place.

Parameters:

value – Separator string (e.g., “:”, “ -> “, “ = “).

setdefault(key: Any, default: Any = None) → Any

Set default, notifying observers.

simple() → Self

Apply simple key: value formatting in-place.

Clean, minimal display with colon separators.

spaced() → Self

Apply generous spacing style in-place.

More padding and gaps for readability.

striped() → Self

Apply striped table style in-place.

Creates an alternating row colors table.

styled(**styles: str | CSSValue) → Self

Apply additional container styles in-place.

Parameters:

**styles – CSS property-value pairs for the container. Accepts both strings and CSS type objects (Color, Size, etc.)

Returns:

Self for method chaining.

update(*args: Any, **kwargs: Any) → None

Update dict, notifying observers.

value_background(value: Color | str) → Self

Apply background color to values in-place.

Parameters:

value – CSS color value (e.g., “lightgray”, Color.hex(“#eee”)).

value_bold() → Self

Apply bold style to values in-place.

value_color(value: Color | str) → Self

Apply color to values in-place.

Parameters:

value – CSS color value (e.g., “green”, Color.green).

value_italic() → Self

Apply italic style to values in-place.

value_padding(value: Spacing | str | int | float) → Self

Apply padding to values in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10), Spacing.all(10)).

value_styled(**styles: str | CSSValue) → Self

Apply styles to values in-place.

Parameters:

**styles – CSS property-value pairs for values. Accepts both strings and CSS type objects (Color, Size, etc.)

vertical() → Self

Apply vertical layout (entries stacked) in-place.

width(value: Size | str | int | float) → Self

Apply container width in-place.

Parameters:

value – CSS width value (e.g., “300px”, Size.px(300), Size.percent(100)).

class animaid.HTMLDivider(label: str | None = None, **styles: str | CSSValue)

Bases: HTMLObject

A visual separator (horizontal or vertical line).

HTMLDivider creates a line to visually separate content sections. It can be horizontal (default) or vertical (for use in rows).

Examples

>>> from animaid import HTMLDivider
>>> divider = HTMLDivider()  # Simple horizontal line

>>> # With label
>>> divider = HTMLDivider("OR")

>>> # Vertical divider for rows
>>> divider = HTMLDivider().vertical()

>>> # Styled divider
>>> divider = HTMLDivider().dashed().color("gray")

add_class(*class_names: str) → HTMLDivider

Add CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

bold() → HTMLDivider

Apply bold divider styling (thicker, darker).

Returns:

Self for method chaining.

color(value: Color | str) → HTMLDivider

Set the divider color.

Parameters:

value – Color enum or CSS color string.

Returns:

Self for method chaining.

dashed() → HTMLDivider

Set dashed line style.

Returns:

Self for method chaining.

dotted() → HTMLDivider

Set dotted line style.

Returns:

Self for method chaining.

horizontal() → HTMLDivider

Make the divider horizontal (default).

Returns:

Self for method chaining.

margin(size: Size | str) → HTMLDivider

Set the margin around the divider.

Parameters:

size – Margin size.

Returns:

Self for method chaining.

render() → str

Render the divider.

Returns:

HTML string for the divider.

set_label(text: str | None) → HTMLDivider

Set or remove the divider label.

Parameters:

text – Label text, or None to remove.

Returns:

Self for method chaining.

solid() → HTMLDivider

Set solid line style.

Returns:

Self for method chaining.

style(value: DividerStyle | str) → HTMLDivider

Set the line style.

Parameters:

value – DividerStyle enum or CSS border-style string.

Returns:

Self for method chaining.

styled(**styles: str | CSSValue) → HTMLDivider

Apply additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

Self for method chaining.

subtle() → HTMLDivider

Apply subtle divider styling (lighter color).

Returns:

Self for method chaining.

thickness(size: Size | str | int) → HTMLDivider

Set the divider thickness.

Parameters:

size – Thickness (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

vertical() → HTMLDivider

Make the divider vertical (for use in flex rows).

Returns:

Self for method chaining.

class animaid.HTMLFloat(value: float = 0.0, **styles: str | CSSValue)

Bases: HTMLObject, float

A float subclass that renders as styled HTML.

HTMLFloat behaves like a regular Python float but includes methods for applying CSS styles, number formatting, and rendering to HTML. All styling methods modify the object in-place and return self for method chaining.

Examples

>>> n = HTMLFloat(3.14159)
>>> n.bold().red().render()
'<span style="font-weight: bold; color: red">3.14159</span>'

>>> HTMLFloat(1234.5678).comma().render()
'<span>1,234.5678</span>'

>>> HTMLFloat(0.856).percent().render()
'<span>85.60%</span>'

>>> HTMLFloat(3.14159).decimal(2).render()
'<span>3.14</span>'

add_class(*class_names: str) → Self

Add CSS classes in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

background(value: Color | str) → Self

Apply specified background color in-place.

badge() → Self

Apply badge/pill style in-place.

black() → Self

Apply black text color in-place.

blue() → Self

Apply blue text color in-place.

bold() → Self

Apply bold text style in-place.

border(value: Border | str) → Self

Apply specified border in-place.

border_radius(value: Size | str | int | float) → Self

Apply specified border radius in-place.

color(value: Color | str) → Self

Apply specified text color in-place.

comma() → Self

Apply thousand separator formatting in-place.

Examples

>>> HTMLFloat(1234567.89).comma().render()
'<span>1,234,567.89</span>'

currency(symbol: str = '$', decimals: int = 2) → Self

Apply currency formatting in-place.

Parameters:

• symbol – Currency symbol (default “$”)

• decimals – Number of decimal places (default 2)

Examples

>>> HTMLFloat(1000.5).currency().render()
'<span>$1,000.50</span>'
>>> HTMLFloat(1000.5).currency("€", 0).render()
'<span>€1,000</span>'

decimal(places: int = 2) → Self

Apply fixed decimal places formatting in-place.

Parameters:

places – Number of decimal places (default 2)

Examples

>>> HTMLFloat(3.14159).decimal(2).render()
'<span>3.14</span>'
>>> HTMLFloat(3.1).decimal(4).render()
'<span>3.1000</span>'

error() → Self

Apply error style (red) in-place.

font_size(value: Size | str | int | float) → Self

Apply specified font size in-place.

gray() → Self

Apply gray text color in-place.

green() → Self

Apply green text color in-place.

info() → Self

Apply info style (blue) in-place.

italic() → Self

Apply italic text style in-place.

large() → Self

Apply large text size (20px) in-place.

margin(value: Spacing | str | int | float) → Self

Apply specified margin in-place.

medium() → Self

Apply medium text size (16px) in-place.

monospace() → Self

Apply monospace font in-place.

orange() → Self

Apply orange text color in-place.

padding(value: Spacing | str | int | float) → Self

Apply specified padding in-place.

percent(decimals: int = 2) → Self

Apply percentage formatting in-place.

The value is multiplied by 100 for display.

Parameters:

decimals – Number of decimal places (default 2)

Examples

>>> HTMLFloat(0.856).percent().render()
'<span>85.60%</span>'
>>> HTMLFloat(0.5).percent(0).render()
'<span>50%</span>'

purple() → Self

Apply purple text color in-place.

red() → Self

Apply red text color in-place.

render() → str

Return HTML representation of this float.

Returns:

A string containing valid HTML.

scientific(precision: int = 2) → Self

Apply scientific notation formatting in-place.

Parameters:

precision – Number of decimal places in mantissa (default 2)

Examples

>>> HTMLFloat(1234567.89).scientific().render()
'<span>1.23e+06</span>'

significant(figures: int = 3) → Self

Apply significant figures formatting in-place.

Parameters:

figures – Number of significant figures (default 3)

Examples

>>> HTMLFloat(3.14159).significant(3).render()
'<span>3.14</span>'
>>> HTMLFloat(0.00123456).significant(2).render()
'<span>0.0012</span>'

small() → Self

Apply small text size (14px) in-place.

strikethrough() → Self

Apply strikethrough text style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional inline styles in-place.

Parameters:

**styles – CSS property-value pairs.

Returns:

Self for method chaining.

success() → Self

Apply success style (green) in-place.

tag(tag_name: str) → Self

Change the HTML tag in-place.

Parameters:

tag_name – The HTML tag to use (e.g., “div”, “p”, “strong”).

Returns:

Self for method chaining.

underline() → Self

Apply underline text style in-place.

warning() → Self

Apply warning style (orange) in-place.

white() → Self

Apply white text color in-place.

xl() → Self

Apply extra-large text size (24px) in-place.

xs() → Self

Apply extra-small text size (12px) in-place.

xxl() → Self

Apply 2x extra-large text size (32px) in-place.

yellow() → Self

Apply yellow text color in-place.

class animaid.HTMLInt(value: int = 0, **styles: str | CSSValue)

Bases: HTMLObject, int

An int subclass that renders as styled HTML.

HTMLInt behaves like a regular Python int but includes methods for applying CSS styles, number formatting, and rendering to HTML. All styling methods modify the object in-place and return self for method chaining.

Examples

>>> n = HTMLInt(42)
>>> n.bold().red().render()
'<span style="font-weight: bold; color: red">42</span>'

>>> HTMLInt(1234567).comma().render()
'<span>1,234,567</span>'

>>> HTMLInt(1000).currency("$").bold().render()
'<span style="font-weight: bold">$1,000</span>'

>>> HTMLInt(1).ordinal().render()
'<span>1st</span>'

add_class(*class_names: str) → Self

Add CSS classes in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

background(value: Color | str) → Self

Apply specified background color in-place.

badge() → Self

Apply badge/pill style in-place.

black() → Self

Apply black text color in-place.

blue() → Self

Apply blue text color in-place.

bold() → Self

Apply bold text style in-place.

border(value: Border | str) → Self

Apply specified border in-place.

border_radius(value: Size | str | int | float) → Self

Apply specified border radius in-place.

color(value: Color | str) → Self

Apply specified text color in-place.

comma() → Self

Apply thousand separator formatting in-place.

Examples

>>> HTMLInt(1234567).comma().render()
'<span>1,234,567</span>'

currency(symbol: str = '$') → Self

Apply currency formatting in-place.

Parameters:

symbol – Currency symbol (default “$”)

Examples

>>> HTMLInt(1000).currency().render()
'<span>$1,000</span>'
>>> HTMLInt(1000).currency("€").render()
'<span>€1,000</span>'

error() → Self

Apply error style (red) in-place.

font_size(value: Size | str | int | float) → Self

Apply specified font size in-place.

gray() → Self

Apply gray text color in-place.

green() → Self

Apply green text color in-place.

info() → Self

Apply info style (blue) in-place.

italic() → Self

Apply italic text style in-place.

large() → Self

Apply large text size (20px) in-place.

margin(value: Spacing | str | int | float) → Self

Apply specified margin in-place.

medium() → Self

Apply medium text size (16px) in-place.

monospace() → Self

Apply monospace font in-place.

orange() → Self

Apply orange text color in-place.

ordinal() → Self

Apply ordinal formatting (1st, 2nd, 3rd, etc.) in-place.

Examples

>>> HTMLInt(1).ordinal().render()
'<span>1st</span>'
>>> HTMLInt(22).ordinal().render()
'<span>22nd</span>'

padded(width: int = 2) → Self

Apply zero-padding formatting in-place.

Parameters:

width – Minimum width (default 2)

Examples

>>> HTMLInt(7).padded(3).render()
'<span>007</span>'

padding(value: Spacing | str | int | float) → Self

Apply specified padding in-place.

percent() → Self

Apply percentage formatting in-place.

Examples

>>> HTMLInt(85).percent().render()
'<span>85%</span>'

purple() → Self

Apply purple text color in-place.

red() → Self

Apply red text color in-place.

render() → str

Return HTML representation of this integer.

Returns:

A string containing valid HTML.

small() → Self

Apply small text size (14px) in-place.

strikethrough() → Self

Apply strikethrough text style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional inline styles in-place.

Parameters:

**styles – CSS property-value pairs.

Returns:

Self for method chaining.

success() → Self

Apply success style (green) in-place.

tag(tag_name: str) → Self

Change the HTML tag in-place.

Parameters:

tag_name – The HTML tag to use (e.g., “div”, “p”, “strong”).

Returns:

Self for method chaining.

underline() → Self

Apply underline text style in-place.

warning() → Self

Apply warning style (orange) in-place.

white() → Self

Apply white text color in-place.

xl() → Self

Apply extra-large text size (24px) in-place.

xs() → Self

Apply extra-small text size (12px) in-place.

xxl() → Self

Apply 2x extra-large text size (32px) in-place.

yellow() → Self

Apply yellow text color in-place.

class animaid.HTMLList(items: list[Any] | None = None, **styles: str | CSSValue)

Bases: HTMLObject, list

A list subclass that renders as styled HTML.

HTMLList behaves like a regular Python list but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining. Supports vertical, horizontal, and grid layouts.

Examples

>>> items = HTMLList(["Apple", "Banana", "Cherry"])
>>> items.render()
'<ul><li>Apple</li><li>Banana</li><li>Cherry</li></ul>'

>>> items.horizontal().gap("10px").render()
'<div style="display: flex; flex-direction: row; gap: 10px">...</div>'

>>> HTMLList([1, 2, 3]).ordered().render()
'<ol><li>1</li><li>2</li><li>3</li></ol>'

add_class(*class_names: str) → Self

Add CSS classes on the container in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

add_item_class(*class_names: str) → Self

Add CSS classes to each item in-place.

Parameters:

*class_names – CSS class names to add to items.

align_items(value: AlignItems | str) → Self

Apply specified cross-axis alignment in-place.

Parameters:

value – CSS align-items value (e.g., “center”, AlignItems.CENTER).

append(item: Any) → None

Append item, notifying observers.

background(value: Color | str) → Self

Apply background color on the container in-place.

Parameters:

value – CSS color value (e.g., “white”, Color.white, Color.hex(“#fff”)).

border(value: Border | str) → Self

Apply border around the container in-place.

Parameters:

value – CSS border value (e.g., “1px solid black”, Border.solid()).

border_radius(value: Size | str | int | float) → Self

Apply rounded corners on the container in-place.

Parameters:

value – CSS border-radius value (e.g., “5px”, Size.px(5)).

bulleted() → Self

Apply bulleted list style in-place.

cards() → Self

Apply card list style with shadows and spacing in-place.

Creates a visually appealing list where each item looks like a card.

center() → Self

Apply centered alignment on both axes in-place.

clear() → None

Clear list, notifying observers.

color(value: Color | str) → Self

Apply text color in-place.

Parameters:

value – CSS color value (e.g., “black”, Color.black).

compact() → Self

Apply minimal spacing style in-place.

extend(items: Any) → None

Extend list, notifying observers.

gap(value: Size | str | int | float) → Self

Apply specified gap between items in-place.

Parameters:

value – CSS gap value (e.g., “10px”, Size.px(10), Size.rem(1)).

grid(columns: int = 3) → Self

Apply CSS grid layout in-place.

Parameters:

columns – Number of columns in the grid.

Returns:

Self for method chaining.

height(value: Size | str | int | float) → Self

Apply specified height in-place.

Parameters:

value – CSS height value (e.g., “200px”, Size.px(200), Size.vh(100)).

horizontal() → Self

Apply horizontal layout in-place.

Items are arranged left to right using flexbox.

horizontal_reverse() → Self

Apply reversed horizontal layout in-place.

Items are arranged right to left.

inline() → Self

Apply inline style in-place.

Creates a simple inline list separated by spacing.

insert(index: Any, item: Any) → None

Insert item, notifying observers.

item_background(value: Color | str) → Self

Apply background color on each item in-place.

Parameters:

value – CSS color value.

item_border(value: Border | str) → Self

Apply border around each item in-place.

Parameters:

value – CSS border value for items.

item_border_radius(value: Size | str | int | float) → Self

Apply rounded corners on each item in-place.

Parameters:

value – CSS border-radius value for items.

item_margin(value: Spacing | str | int | float) → Self

Apply margin around each item in-place.

Parameters:

value – CSS margin value for items.

item_padding(value: Spacing | str | int | float) → Self

Apply padding inside each item in-place.

Parameters:

value – CSS padding value for items.

justify_content(value: JustifyContent | str) → Self

Apply specified main-axis alignment in-place.

Parameters:

value – CSS justify-content value (e.g., “space-between”).

margin(value: Spacing | str | int | float) → Self

Apply margin outside the container in-place.

Parameters:

value – CSS margin value (e.g., “10px”, Size.px(10), Spacing.all(10)).

max_width(value: Size | str | int | float) → Self

Apply maximum width constraint in-place.

Parameters:

value – CSS max-width value (e.g., “800px”, Size.px(800)).

menu() → Self

Apply vertical menu style in-place.

Creates a clean vertical menu suitable for navigation.

numbered() → Self

Apply numbered list style in-place.

ordered() → Self

Apply ordered list (<ol>) format in-place.

padding(value: Spacing | str | int | float) → Self

Apply padding inside the container in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10)).

pills() → Self

Apply pill/badge style in-place.

Creates a horizontal list of pill-shaped items.

plain() → Self

Apply plain div container (no bullets/numbers) in-place.

pop(index: Any = -1) → Any

Pop item, notifying observers.

remove(item: Any) → None

Remove item, notifying observers.

render() → str

Return HTML representation of this list.

Returns:

A string containing valid HTML.

reverse() → None

Reverse list, notifying observers.

separator(value: Border | str) → Self

Apply separator lines between items in-place.

Unlike item_border, this only adds borders between items, not on the outer edges.

Parameters:

value – CSS border value for separators.

sort(*, key: Any = None, reverse: bool = False) → None

Sort list, notifying observers.

spaced() → Self

Apply generous spacing style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional container styles in-place.

Parameters:

**styles – CSS property-value pairs for the container. Accepts both strings and CSS type objects (Color, Size, etc.)

Returns:

Self for method chaining.

tags() → Self

Apply tags/labels style in-place.

Creates a horizontal list of tag-style items.

unordered() → Self

Apply unordered list (<ul>) format in-place.

vertical() → Self

Apply vertical layout (default) in-place.

Items are stacked top to bottom.

vertical_reverse() → Self

Apply reversed vertical layout in-place.

Items are stacked bottom to top.

width(value: Size | str | int | float) → Self

Apply specified width in-place.

Parameters:

value – CSS width value (e.g., “100px”, Size.px(100), Size.percent(50)).

class animaid.HTMLObject

Bases: ABC

Abstract base class for all HTML-renderable types.

All HTML* types (HTMLString, HTMLList, HTMLDict) inherit from this to ensure a consistent interface for rendering Python objects as styled HTML. When rendering nested objects, any item that is an HTMLObject will have its render() method called automatically.

abstractmethod add_class(*class_names: str) → Self

Return a copy with additional CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

A new instance with the additional classes.

abstractmethod render() → str

Return HTML representation of this object.

Returns:

A string containing valid HTML that can be embedded in a page.

abstractmethod styled(**styles: str) → Self

Return a copy with additional inline styles.

Style names use Python convention (underscores) and are converted to CSS convention (hyphens) automatically.

Parameters:

**styles – CSS property-value pairs, e.g., font_size=”16px”

Returns:

A new instance with the combined styles.

class animaid.HTMLRow(children: list[Any] | None = None, **styles: str | CSSValue)

Bases: HTMLContainer

A horizontal flex container for arranging items in a row.

HTMLRow uses CSS flexbox with flex-direction: row to arrange children horizontally. It provides methods for controlling alignment, justification, wrapping, and spacing.

Examples

>>> from animaid import HTMLRow, HTMLButton
>>> row = HTMLRow([
...     HTMLButton("Save").primary(),
...     HTMLButton("Cancel"),
... ])

>>> # With alignment and gap
>>> row = HTMLRow([item1, item2, item3]).gap(10).align(AlignItems.CENTER)

>>> # Button row preset
>>> row = HTMLRow(buttons).buttons()

add_class(*class_names: str) → HTMLRow

Add CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

align(value: AlignItems | str) → HTMLRow

Set vertical alignment of items within the row.

Parameters:

value – AlignItems enum or CSS string (start, center, end, stretch, baseline).

Returns:

Self for method chaining.

Example

>>> row.align(AlignItems.CENTER)
>>> row.align("center")  # Also works

buttons() → HTMLRow

Apply button row styling preset.

Creates a row with appropriate gap and end-alignment, suitable for action buttons in forms or dialogs.

Returns:

Self for method chaining.

centered() → HTMLRow

Center all items both horizontally and vertically.

Returns:

Self for method chaining.

end() → HTMLRow

Align items to the end (right).

Returns:

Self for method chaining.

gap(size: Size | str | int) → HTMLRow

Set the gap between child elements.

Parameters:

size – Gap size.

Returns:

Self for method chaining.

height(size: Size | str | int) → HTMLRow

Set container height.

Parameters:

size – Height.

Returns:

Self for method chaining.

justify(value: JustifyContent | str) → HTMLRow

Set horizontal distribution of items within the row.

Parameters:

value – JustifyContent enum or CSS string (start, center, end, space-between, space-around, space-evenly).

Returns:

Self for method chaining.

Example

>>> row.justify(JustifyContent.SPACE_BETWEEN)
>>> row.justify("space-between")  # Also works

margin(size: Spacing | Size | str | int) → HTMLRow

Set external margin.

Parameters:

size – Margin size.

Returns:

Self for method chaining.

min_item_width(size: Size | str | int) → HTMLRow

Set minimum width for child items (via CSS custom property).

This works best with .wrap() to prevent items from becoming too small before wrapping.

Parameters:

size – Minimum item width.

Returns:

Self for method chaining.

nowrap() → HTMLRow

Prevent items from wrapping (default behavior).

Returns:

Self for method chaining.

padding(size: Spacing | Size | str | int) → HTMLRow

Set internal padding.

Parameters:

size – Padding size.

Returns:

Self for method chaining.

reverse() → HTMLRow

Reverse the order of items.

Returns:

Self for method chaining.

spaced() → HTMLRow

Distribute items with space between them.

Returns:

Self for method chaining.

start() → HTMLRow

Align items to the start (left).

Returns:

Self for method chaining.

styled(**styles: str | CSSValue) → HTMLRow

Apply additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

Self for method chaining.

toolbar() → HTMLRow

Apply toolbar styling preset.

Creates a compact row suitable for toolbar layouts.

Returns:

Self for method chaining.

width(size: Size | str | int) → HTMLRow

Set container width.

Parameters:

size – Width.

Returns:

Self for method chaining.

wrap(value: FlexWrap | str = FlexWrap.WRAP) → HTMLRow

Allow items to wrap to the next line.

Parameters:

value – FlexWrap enum or CSS string (wrap, nowrap, wrap-reverse). Default is WRAP.

Returns:

Self for method chaining.

Example

>>> row.wrap()  # Enable wrapping
>>> row.wrap(FlexWrap.WRAP_REVERSE)  # Wrap in reverse order

class animaid.HTMLSelect(options: list[str], value: str | None = None)

Bases: object

A dropdown select widget with two-way binding.

The value property is automatically synced from the browser when the user selects an option.

Examples

>>> select = HTMLSelect(options=["Red", "Green", "Blue"])
>>> select = HTMLSelect(
...     options=["Small", "Medium", "Large"],
...     value="Medium"
... ).on_change(handle_change)

# With App - two-way binding >>> with App() as app: … color = HTMLSelect(options=[“Red”, “Green”, “Blue”]) … app.add(color) … # Later, read the current value: … print(color.value) # Selected option synced from browser

add_class(*class_names: str) → HTMLSelect

Return a copy with additional CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

A new instance with the additional classes.

large() → HTMLSelect

Return a copy with larger text and padding.

Returns:

A new instance with large styling.

on_change(callback: Callable[[str], None]) → HTMLSelect

Register a callback for selection changes.

The callback is called when the user selects a different option.

Parameters:

callback – A function that takes the new selected value as argument.

Returns:

Self for method chaining.

Examples

>>> def handle_change(value):
...     print(f"Selected: {value}")
>>> select = HTMLSelect(["A", "B", "C"]).on_change(handle_change)

property options: list[str]

Get the list of options.

render() → str

Return HTML representation of this select.

Returns:

A string containing valid HTML for the select.

small() → HTMLSelect

Return a copy with smaller text and padding.

Returns:

A new instance with small styling.

styled(**styles: str) → HTMLSelect

Return a copy with additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

A new instance with the combined styles.

property value: str

Get the currently selected value (thread-safe).

The value is automatically synced from the browser when the user selects an option.

Returns:

The currently selected option string.

wide() → HTMLSelect

Return a copy that expands to full width.

Returns:

A new instance with full width styling.

class animaid.HTMLSet(items: Iterable[Any] = (), **styles: str | CSSValue)

Bases: HTMLObject, set

A set subclass that renders as styled HTML.

HTMLSet behaves like a regular Python set but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining. Items are automatically deduplicated (set behavior). Mutations trigger notifications for reactive updates.

Examples

>>> s = HTMLSet({1, 2, 3})
>>> s.render()
'<span>{1, 2, 3}</span>'

>>> s.horizontal().pills().render()
'<div style="display: flex; ...">...</div>'

>>> HTMLSet([1, 1, 2, 2, 3])  # Duplicates removed
HTMLSet({1, 2, 3})

add(item: Any) → None

Add item, notifying observers.

add_class(*class_names: str) → Self

Add CSS classes on the container in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

add_item_class(*class_names: str) → Self

Add CSS classes to each item in-place.

align_items(value: AlignItems | str) → Self

Apply specified cross-axis alignment in-place.

background(value: Color | str) → Self

Apply background color on the container in-place.

border(value: Border | str) → Self

Apply border around the container in-place.

border_radius(value: Size | str | int | float) → Self

Apply rounded corners on the container in-place.

braces() → Self

Apply braces format (default) in-place.

center() → Self

Apply centered alignment on both axes in-place.

clear() → None

Clear set, notifying observers.

color(value: Color | str) → Self

Apply text color in-place.

compact() → Self

Apply minimal spacing style in-place.

difference(*others: Iterable[Any]) → Self

Return difference with other sets, preserving settings.

difference_update(*others: Iterable[Any]) → None

Difference update, notifying observers.

discard(item: Any) → None

Discard item, notifying observers.

gap(value: Size | str | int | float) → Self

Apply specified gap between items in-place.

grid(columns: int = 3) → Self

Apply CSS grid layout in-place.

Parameters:

columns – Number of columns in the grid.

height(value: Size | str | int | float) → Self

Apply specified height in-place.

horizontal() → Self

Apply horizontal layout (default) in-place.

horizontal_reverse() → Self

Apply reversed horizontal layout in-place.

inline() → Self

Apply inline style in-place.

intersection(*others: Iterable[Any]) → Self

Return intersection with other sets, preserving settings.

intersection_update(*others: Iterable[Any]) → None

Intersection update, notifying observers.

item_background(value: Color | str) → Self

Apply background color on each item in-place.

item_border(value: Border | str) → Self

Apply border around each item in-place.

item_border_radius(value: Size | str | int | float) → Self

Apply rounded corners on each item in-place.

item_margin(value: Spacing | str | int | float) → Self

Apply margin around each item in-place.

item_padding(value: Spacing | str | int | float) → Self

Apply padding inside each item in-place.

justify_content(value: JustifyContent | str) → Self

Apply specified main-axis alignment in-place.

margin(value: Spacing | str | int | float) → Self

Apply margin outside the container in-place.

padding(value: Spacing | str | int | float) → Self

Apply padding inside the container in-place.

pills() → Self

Apply pill/badge style in-place.

plain() → Self

Apply plain format (without brace decoration) in-place.

pop() → Any

Pop item, notifying observers.

remove(item: Any) → None

Remove item, notifying observers.

render() → str

Return HTML representation of this set.

Returns:

A string containing valid HTML.

separator(value: Border | str) → Self

Apply separator lines between items in-place.

sorted() → Self

Apply sorted rendering order in-place.

spaced() → Self

Apply generous spacing style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional container styles in-place.

Parameters:

**styles – CSS property-value pairs for the container.

Returns:

Self for method chaining.

symmetric_difference(other: Iterable[Any]) → Self

Return symmetric difference with other set, preserving settings.

symmetric_difference_update(other: Iterable[Any]) → None

Symmetric difference update, notifying observers.

tags() → Self

Apply tags/labels style in-place.

union(*others: Iterable[Any]) → Self

Return union with other sets, preserving settings.

unsorted() → Self

Apply iteration order (no sorting) in-place.

update(*others: Iterable[Any]) → None

Update set, notifying observers.

vertical() → Self

Apply vertical layout in-place.

vertical_reverse() → Self

Apply reversed vertical layout in-place.

width(value: Size | str | int | float) → Self

Apply specified width in-place.

class animaid.HTMLSlider(min: float = 0, max: float = 100, value: float | None = None, step: float = 1)

Bases: object

A range slider widget with two-way numeric binding.

The value property is automatically synced from the browser when the user moves the slider.

Examples

>>> slider = HTMLSlider(min=0, max=100, value=50)
>>> slider = HTMLSlider(min=0, max=1, step=0.1).on_change(handle_change)

# With App - two-way binding >>> with App() as app: … volume = HTMLSlider(min=0, max=100, value=75) … app.add(volume) … # Later, read the current value: … print(volume.value) # Numeric value synced from browser

add_class(*class_names: str) → HTMLSlider

Return a copy with additional CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

A new instance with the additional classes.

property max: float

Get the maximum value.

property min: float

Get the minimum value.

on_change(callback: Callable[[float], None]) → HTMLSlider

Register a callback for value changes.

The callback is called when the user moves the slider.

Parameters:

callback – A function that takes the new value as argument.

Returns:

Self for method chaining.

Examples

>>> def handle_change(value):
...     print(f"Slider value: {value}")
>>> slider = HTMLSlider(0, 100).on_change(handle_change)

render() → str

Return HTML representation of this slider.

Returns:

A string containing valid HTML for the slider.

property step: float

Get the step increment.

styled(**styles: str) → HTMLSlider

Return a copy with additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

A new instance with the combined styles.

thick() → HTMLSlider

Return a copy with a thicker slider track.

Returns:

A new instance with thick styling.

thin() → HTMLSlider

Return a copy with a thinner slider track.

Returns:

A new instance with thin styling.

property value: float

Get the current value (thread-safe).

The value is automatically synced from the browser when the user moves the slider.

Returns:

The current numeric value of the slider.

wide() → HTMLSlider

Return a copy that expands to full width.

Returns:

A new instance with full width styling.

class animaid.HTMLSpacer(**styles: str | CSSValue)

Bases: HTMLObject

An empty space element for layout control.

HTMLSpacer creates invisible space between elements. It can be fixed-size or flexible (expands to fill available space in flex containers).

Examples

>>> from animaid import HTMLSpacer, HTMLRow, HTMLButton

>>> # Fixed height spacer
>>> spacer = HTMLSpacer().height(20)

>>> # Flexible spacer (pushes items apart in flex containers)
>>> row = HTMLRow([
...     HTMLButton("Left"),
...     HTMLSpacer().flex(),  # Takes remaining space
...     HTMLButton("Right"),
... ])

>>> # Fixed width spacer in a row
>>> row = HTMLRow([item1, HTMLSpacer().width(50), item2])

add_class(*class_names: str) → HTMLSpacer

Add CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

flex(grow: int = 1) → HTMLSpacer

Make the spacer flexible (expands to fill available space).

In a flex container (HTMLRow or HTMLColumn), a flex spacer will expand to take up any remaining space, pushing other items apart.

Parameters:

grow – Flex grow value (default 1).

Returns:

Self for method chaining.

Example

>>> # Push button to the right
>>> row = HTMLRow([
...     HTMLString("Title"),
...     HTMLSpacer().flex(),
...     HTMLButton("Action"),
... ])

grow(value: int = 1) → HTMLSpacer

Set flex-grow value.

Parameters:

value – Flex grow value.

Returns:

Self for method chaining.

height(size: Size | str | int) → HTMLSpacer

Set a fixed height.

Parameters:

size – Height (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

lg() → HTMLSpacer

Large spacer (24px).

Returns:

Self for method chaining.

md() → HTMLSpacer

Medium spacer (16px).

Returns:

Self for method chaining.

render() → str

Render the spacer.

Returns:

HTML string for the spacer div.

shrink(value: int = 0) → HTMLSpacer

Set flex-shrink value.

Parameters:

value – Flex shrink value.

Returns:

Self for method chaining.

size(width: Size | str | int, height: Size | str | int) → HTMLSpacer

Set both width and height.

Parameters:

• width – Width value.

• height – Height value.

Returns:

Self for method chaining.

sm() → HTMLSpacer

Small spacer (8px).

Returns:

Self for method chaining.

styled(**styles: str | CSSValue) → HTMLSpacer

Apply additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

Self for method chaining.

width(size: Size | str | int) → HTMLSpacer

Set a fixed width.

Parameters:

size – Width (Size, CSS string, or int pixels).

Returns:

Self for method chaining.

xl() → HTMLSpacer

Extra large spacer (32px).

Returns:

Self for method chaining.

xs() → HTMLSpacer

Extra small spacer (4px).

Returns:

Self for method chaining.

class animaid.HTMLString(content: str = '', **styles: str | CSSValue)

Bases: HTMLObject, str

A string subclass that renders as styled HTML.

HTMLString behaves like a regular Python string but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining.

Examples

>>> s = HTMLString("Hello World")
>>> s.bold().color("red").render()
'<span style="font-weight: bold; color: red">Hello World</span>'

>>> s = HTMLString("Click me", color="blue", text_decoration="underline")
>>> s.render()
'<span style="color: blue; text-decoration: underline">Click me</span>'

add_class(*class_names: str) → Self

Add CSS classes in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

Example

>>> s = HTMLString("Hello").add_class("highlight", "important")
>>> s.render()
'<span class="highlight important">Hello</span>'

background(value: Color | str) → Self

Apply specified background color in-place.

Parameters:

value – CSS color value (e.g., “yellow”, Color.yellow)

badge() → Self

Apply badge/pill style in-place.

bg_black() → Self

Apply black background in-place.

bg_blue() → Self

Apply blue background in-place.

bg_gray() → Self

Apply gray background in-place.

bg_green() → Self

Apply green background in-place.

bg_orange() → Self

Apply orange background in-place.

bg_pink() → Self

Apply pink background in-place.

bg_purple() → Self

Apply purple background in-place.

bg_red() → Self

Apply red background in-place.

bg_white() → Self

Apply white background in-place.

bg_yellow() → Self

Apply yellow background in-place.

black() → Self

Apply black text color in-place.

blue() → Self

Apply blue text color in-place.

bold() → Self

Apply bold text style in-place.

border(value: Border | str) → Self

Apply specified border in-place.

Parameters:

value – CSS border value (e.g., “1px solid black”, Border.solid())

border_radius(value: Size | str | int | float) → Self

Apply specified border radius in-place.

Parameters:

value – CSS border-radius value (e.g., “5px”, Size.px(5), Size.percent(50))

capitalize() → Self

Apply capitalize text transform in-place.

code() → Self

Apply inline code style in-place.

color(value: Color | str) → Self

Apply specified text color in-place.

Parameters:

value – CSS color value (e.g., “red”, “#ff0000”, Color.red)

display(value: Display | str) → Self

Apply specified display mode in-place.

Parameters:

value – CSS display value (e.g., “block”, “flex”, Display.FLEX)

error() → Self

Apply error style (red) in-place.

font_family(value: str) → Self

Apply specified font family in-place.

Parameters:

value – CSS font-family value.

font_size(value: Size | str | int | float) → Self

Apply specified font size in-place.

Parameters:

value – CSS size value (e.g., “16px”, Size.px(16), Size.em(1.2))

gray() → Self

Apply gray text color in-place.

green() → Self

Apply green text color in-place.

height(value: Size | str | int | float) → Self

Apply specified height in-place.

Parameters:

value – CSS height value (e.g., “50px”, Size.px(50), Size.vh(100))

highlight() → Self

Apply highlight style (yellow background) in-place.

info() → Self

Apply info style (blue) in-place.

italic() → Self

Apply italic text style in-place.

large() → Self

Apply large text size (20px) in-place.

link() → Self

Apply link style in-place.

lowercase() → Self

Apply lowercase text transform in-place.

margin(value: Spacing | str | int | float) → Self

Apply specified margin in-place.

Parameters:

value – CSS margin value (e.g., “10px”, Size.px(10), Spacing.all(10))

medium() → Self

Apply medium text size (16px) in-place.

monospace() → Self

Apply monospace font in-place.

muted() → Self

Apply muted/secondary text style in-place.

nowrap() → Self

Apply nowrap white-space style in-place.

opacity(value: str | float) → Self

Apply specified opacity in-place.

Parameters:

value – CSS opacity value (0.0 to 1.0)

orange() → Self

Apply orange text color in-place.

padding(value: Spacing | str | int | float) → Self

Apply specified padding in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10))

pink() → Self

Apply pink text color in-place.

purple() → Self

Apply purple text color in-place.

red() → Self

Apply red text color in-place.

render() → str

Return HTML representation of this string.

The string content is HTML-escaped to prevent XSS.

Returns:

A string containing valid HTML.

Example

>>> HTMLString("<script>alert('xss')</script>").render()
'<span>&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;</span>'

small() → Self

Apply small text size (14px) in-place.

strikethrough() → Self

Apply strikethrough text style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional inline styles in-place.

Style names use Python convention (underscores) and are converted to CSS convention (hyphens) automatically.

Parameters:

**styles – CSS property-value pairs. Accepts strings and CSS types. e.g., font_size=”16px” or font_size=Size.px(16)

Returns:

Self for method chaining.

Example

>>> s = HTMLString("Hello").styled(color="red", font_size="20px")
>>> s.render()
'<span style="color: red; font-size: 20px">Hello</span>'

>>> s = HTMLString("Hello").styled(color=Color.red, font_size=Size.px(20))
>>> s.render()
'<span style="color: red; font-size: 20px">Hello</span>'

success() → Self

Apply success style (green) in-place.

tag(tag_name: str) → Self

Change the HTML tag in-place.

Parameters:

tag_name – The HTML tag to use (e.g., “div”, “p”, “strong”).

Returns:

Self for method chaining.

Example

>>> s = HTMLString("Hello").tag("strong").render()
'<strong>Hello</strong>'

underline() → Self

Apply underline text style in-place.

uppercase() → Self

Apply uppercase text transform in-place.

warning() → Self

Apply warning style (orange) in-place.

white() → Self

Apply white text color in-place.

width(value: Size | str | int | float) → Self

Apply specified width in-place.

Parameters:

value – CSS width value (e.g., “100px”, Size.px(100), Size.percent(50))

xl() → Self

Apply extra-large text size (24px) in-place.

xs() → Self

Apply extra-small text size (12px) in-place.

xxl() → Self

Apply 2x extra-large text size (32px) in-place.

yellow() → Self

Apply yellow text color in-place.

class animaid.HTMLTextInput(value: str = '', placeholder: str = '')

Bases: object

A text input widget with two-way value binding.

The value property is automatically synced from the browser when the user types in the input field.

Examples

>>> text = HTMLTextInput(placeholder="Enter your name...")
>>> text = HTMLTextInput(value="Default").on_change(handle_change)

# With App - two-way binding >>> with App() as app: … name_input = HTMLTextInput(placeholder=”Name”) … app.add(name_input) … # Later, read the current value: … print(name_input.value) # Value synced from browser

add_class(*class_names: str) → HTMLTextInput

Return a copy with additional CSS classes.

Parameters:

*class_names – CSS class names to add.

Returns:

A new instance with the additional classes.

large() → HTMLTextInput

Return a copy with larger text and padding.

Returns:

A new instance with large styling.

on_change(callback: Callable[[str], None]) → HTMLTextInput

Register a callback for value changes.

The callback is called on each keystroke when the user types.

Parameters:

callback – A function that takes the new value as argument.

Returns:

Self for method chaining.

Examples

>>> def handle_change(value):
...     print(f"Input changed to: {value}")
>>> text = HTMLTextInput().on_change(handle_change)

on_submit(callback: Callable[[str], None]) → HTMLTextInput

Register a callback for submit (Enter key).

The callback is called when the user presses Enter in the input.

Parameters:

callback – A function that takes the submitted value as argument.

Returns:

Self for method chaining.

Examples

>>> def handle_submit(value):
...     print(f"Submitted: {value}")
>>> text = HTMLTextInput().on_submit(handle_submit)

property placeholder: str

Get the placeholder text.

render() → str

Return HTML representation of this text input.

Returns:

A string containing valid HTML for the input.

small() → HTMLTextInput

Return a copy with smaller text and padding.

Returns:

A new instance with small styling.

styled(**styles: str) → HTMLTextInput

Return a copy with additional inline styles.

Parameters:

**styles – CSS property-value pairs.

Returns:

A new instance with the combined styles.

property value: str

Get the current value (thread-safe).

The value is automatically synced from the browser when the user types in the input field.

Returns:

The current text value of the input.

wide() → HTMLTextInput

Return a copy that expands to full width.

Returns:

A new instance with full width styling.

class animaid.HTMLTuple(items: tuple[Any, ...] = (), **styles: str | CSSValue)

Bases: HTMLObject, tuple

A tuple subclass that renders as styled HTML.

HTMLTuple behaves like a regular Python tuple but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining. Supports named tuples with field name display.

Examples

>>> t = HTMLTuple((1, 2, 3))
>>> t.render()
'<div>(1, 2, 3)</div>'

>>> t.horizontal().pills().render()
'<div style="display: flex; ...">...</div>'

>>> from collections import namedtuple
>>> Point = namedtuple('Point', ['x', 'y'])
>>> HTMLTuple(Point(10, 20)).labeled().render()
'<dl><dt>x</dt><dd>10</dd><dt>y</dt><dd>20</dd></dl>'

add_class(*class_names: str) → Self

Add CSS classes on the container in-place.

add_item_class(*class_names: str) → Self

Add CSS classes to each item in-place.

align_items(value: AlignItems | str) → Self

Apply specified cross-axis alignment in-place.

background(value: Color | str) → Self

Apply background color on the container in-place.

border(value: Border | str) → Self

Apply border around the container in-place.

border_radius(value: Size | str | int | float) → Self

Apply rounded corners on the container in-place.

card() → Self

Apply card style for named tuple display in-place.

center() → Self

Apply centered alignment on both axes in-place.

color(value: Color | str) → Self

Apply text color in-place.

compact() → Self

Apply minimal spacing style in-place.

gap(value: Size | str | int | float) → Self

Apply specified gap between items in-place.

grid(columns: int = 3) → Self

Apply CSS grid layout in-place.

height(value: Size | str | int | float) → Self

Apply specified height in-place.

horizontal() → Self

Apply horizontal layout (default) in-place.

horizontal_reverse() → Self

Apply reversed horizontal layout in-place.

inline() → Self

Apply inline style in-place.

item_background(value: Color | str) → Self

Apply background color on each item in-place.

item_border(value: Border | str) → Self

Apply border around each item in-place.

item_border_radius(value: Size | str | int | float) → Self

Apply rounded corners on each item in-place.

item_margin(value: Spacing | str | int | float) → Self

Apply margin around each item in-place.

item_padding(value: Spacing | str | int | float) → Self

Apply padding inside each item in-place.

justify_content(value: JustifyContent | str) → Self

Apply specified main-axis alignment in-place.

labeled() → Self

Apply labeled format showing field names in-place.

For regular tuples, shows index numbers as labels.

margin(value: Spacing | str | int | float) → Self

Apply margin outside the container in-place.

padding(value: Spacing | str | int | float) → Self

Apply padding inside the container in-place.

parentheses() → Self

Apply parentheses format (default) in-place.

pills() → Self

Apply pill/badge style in-place.

plain() → Self

Apply plain format (without parentheses decoration) in-place.

render() → str

Return HTML representation of this tuple.

Returns:

A string containing valid HTML.

separator(value: Border | str) → Self

Apply separator lines between items in-place.

spaced() → Self

Apply generous spacing style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional container styles in-place.

tags() → Self

Apply tags/labels style in-place.

vertical() → Self

Apply vertical layout in-place.

vertical_reverse() → Self

Apply reversed vertical layout in-place.

width(value: Size | str | int | float) → Self

Apply specified width in-place.

class animaid.InputEvent(id: str, event_type: str, value: Any = None, timestamp: float | None = None)

Bases: object

Represents an input event from the browser.

id

The ID of the input element that triggered the event.

Type:

str

event_type

The type of event (e.g., ‘click’, ‘change’, ‘submit’).

Type:

str

value

The value associated with the event (if any).

Type:

Any

timestamp

Unix timestamp when the event occurred.

Type:

float | None

event_type: str

id: str

timestamp: float | None = None

value: Any = None

animaid.Int

alias of HTMLInt

class animaid.JustifyContent(value)

Bases: Enum

CSS justify-content values.

CENTER = 'center'

END = 'end'

FLEX_END = 'flex-end'

FLEX_START = 'flex-start'

SPACE_AROUND = 'space-around'

SPACE_BETWEEN = 'space-between'

SPACE_EVENLY = 'space-evenly'

START = 'start'

STRETCH = 'stretch'

to_css() → str

class animaid.JustifyItems(value)

Bases: Enum

CSS justify-items values for grid containers.

BASELINE = 'baseline'

CENTER = 'center'

END = 'end'

START = 'start'

STRETCH = 'stretch'

to_css() → str

animaid.List

alias of HTMLList

class animaid.Overflow(value)

Bases: Enum

CSS overflow values.

AUTO = 'auto'

CLIP = 'clip'

HIDDEN = 'hidden'

SCROLL = 'scroll'

VISIBLE = 'visible'

to_css() → str

class animaid.PlaceItems(value)

Bases: Enum

CSS place-items shorthand (align + justify).

CENTER = 'center'

END = 'end'

START = 'start'

STRETCH = 'stretch'

to_css() → str

class animaid.Position(value)

Bases: Enum

CSS position values.

ABSOLUTE = 'absolute'

FIXED = 'fixed'

RELATIVE = 'relative'

STATIC = 'static'

STICKY = 'sticky'

to_css() → str

class animaid.RadiusSize(value)

Bases: Enum

Predefined border-radius sizes.

DEFAULT = '4px'

FULL = '9999px'

LG = '8px'

MD = '6px'

NONE = '0'

SM = '2px'

XL = '12px'

XXL = '16px'

to_css() → str

animaid.Row

alias of HTMLRow

animaid.Select

alias of HTMLSelect

animaid.Set

alias of HTMLSet

class animaid.ShadowSize(value)

Bases: Enum

Predefined box-shadow sizes for cards/containers.

DEFAULT = '0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)'

LG = '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)'

MD = '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)'

NONE = 'none'

SM = '0 1px 2px 0 rgba(0, 0, 0, 0.05)'

XL = '0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)'

to_css() → str

class animaid.Size(value: float | str, unit: str = '')

Bases: CSSValue

Represents a CSS size/length value with units.

Examples

>>> Size.px(10)
Size('10px')
>>> Size.em(1.5)
Size('1.5em')
>>> Size.percent(50)
Size('50%')
>>> Size.auto()
Size('auto')

KEYWORDS: ClassVar[set[str]] = {'auto', 'fit-content', 'inherit', 'initial', 'max-content', 'min-content', 'none', 'unset'}

VALID_UNITS: ClassVar[set[str]] = {'%', 'ch', 'cm', 'em', 'ex', 'fr', 'in', 'mm', 'pc', 'pt', 'px', 'rem', 'vh', 'vmax', 'vmin', 'vw'}

classmethod auto() → Size

Create an ‘auto’ size.

classmethod em(value: float) → Size

Create an em size.

classmethod fr(value: float) → Size

Create a fractional unit size (for CSS grid).

classmethod full() → Size

Create a full width/height (100%).

classmethod half() → Size

Create a half width/height (50%).

classmethod inherit() → Size

Create an ‘inherit’ size.

property is_keyword: bool

True if this is a keyword value like ‘auto’.

classmethod lg() → Size

Create a large size (24px).

classmethod md() → Size

Create a medium size (16px).

classmethod none() → Size

Create a ‘none’ size.

classmethod percent(value: float) → Size

Create a percentage size.

classmethod px(value: float) → Size

Create a pixel size.

classmethod quarter() → Size

Create a quarter width/height (25%).

classmethod rem(value: float) → Size

Create a rem size.

classmethod sm() → Size

Create a small size (8px).

classmethod third() → Size

Create a third width/height (33.333%).

to_css() → str

Return the CSS string representation.

property unit: str

The unit string.

property value: float | None

The numeric value, or None for keywords.

classmethod vh(value: float) → Size

Create a viewport height size.

classmethod vw(value: float) → Size

Create a viewport width size.

classmethod xl() → Size

Create an extra-large size (32px).

classmethod xs() → Size

Create an extra-small size (4px).

classmethod xxl() → Size

Create a 2x extra-large size (48px).

classmethod zero() → Size

Create a zero size (0px).

animaid.Slider

alias of HTMLSlider

animaid.Spacer

alias of HTMLSpacer

class animaid.Spacing(top: Size | str | int | float, right: Size | str | int | float | None = None, bottom: Size | str | int | float | None = None, left: Size | str | int | float | None = None)

Bases: CSSValue

Represents CSS spacing (padding/margin) with 1-4 values.

Examples

>>> Spacing.all(Size.px(10))
Spacing('10px')
>>> Spacing.symmetric(Size.px(10), Size.px(20))
Spacing('10px 20px')
>>> Spacing.edges(Size.px(1), Size.px(2), Size.px(3), Size.px(4))
Spacing('1px 2px 3px 4px')

classmethod all(value: Size | str | int | float) → Spacing

Create uniform spacing on all sides.

property bottom: Size

Bottom spacing (same as top if not specified).

classmethod button() → Spacing

Create typical button padding (8px 16px).

classmethod card() → Spacing

Create typical card padding (16px).

classmethod compact() → Spacing

Create compact spacing (4px 8px).

classmethod edges(top: Size | str | int | float, right: Size | str | int | float, bottom: Size | str | int | float, left: Size | str | int | float) → Spacing

Create spacing with explicit values for all four edges.

classmethod horizontal(value: Size | str | int | float) → Spacing

Create horizontal-only spacing (left and right).

classmethod input() → Spacing

Create typical input field padding (8px 12px).

property left: Size

Left spacing (same as right if not specified).

classmethod lg() → Spacing

Create large spacing (24px).

classmethod md() → Spacing

Create medium spacing (16px).

classmethod relaxed() → Spacing

Create relaxed/generous spacing (16px 24px).

property right: Size

Right spacing (same as top if not specified).

classmethod section() → Spacing

Create typical section margins (24px top/bottom, 0 left/right).

classmethod sm() → Spacing

Create small spacing (8px).

classmethod symmetric(vertical: Size | str | int | float, horizontal: Size | str | int | float) → Spacing

Create symmetric spacing (vertical and horizontal).

to_css() → str

Return the CSS spacing value.

property top: Size

Top spacing.

classmethod vertical(value: Size | str | int | float) → Spacing

Create vertical-only spacing (top and bottom).

classmethod xl() → Spacing

Create extra-large spacing (32px).

classmethod xs() → Spacing

Create extra-small spacing (4px).

classmethod zero() → Spacing

Create zero spacing.

animaid.String

alias of HTMLString

class animaid.TextAlign(value)

Bases: Enum

CSS text-align values.

CENTER = 'center'

END = 'end'

JUSTIFY = 'justify'

LEFT = 'left'

RIGHT = 'right'

START = 'start'

to_css() → str

class animaid.TextDecoration(value)

Bases: Enum

CSS text-decoration values.

LINE_THROUGH = 'line-through'

NONE = 'none'

OVERLINE = 'overline'

UNDERLINE = 'underline'

to_css() → str

animaid.TextInput

alias of HTMLTextInput

class animaid.TextTransform(value)

Bases: Enum

CSS text-transform values.

CAPITALIZE = 'capitalize'

LOWERCASE = 'lowercase'

NONE = 'none'

UPPERCASE = 'uppercase'

to_css() → str

animaid.Tuple

alias of HTMLTuple

class animaid.Window(app: App, config: WindowConfig)

Bases: object

Runtime window control for AnimAID applications.

Access this via the app.window property. Provides methods to dynamically control the browser window appearance and behavior.

Examples

>>> with App() as app:
...     app.window.dark()           # Switch to dark theme
...     app.window.set_title("Processing...")
...     app.window.resize(1280, 720)

property background_color: str

Get the current background color.

dark() → Window

Switch to dark theme.

Convenience method equivalent to set_theme(“dark”).

Returns:

Self for method chaining.

Examples

>>> app.window.dark()

fullscreen() → Window

Request fullscreen mode.

Note: Browsers may require user interaction before allowing fullscreen.

Returns:

Self for method chaining.

Examples

>>> app.window.fullscreen()

get_config() → dict[str, Any]

Get the current window configuration as a dictionary.

Used by the server to send initial configuration to clients.

Returns:

Dictionary with current window settings.

handle_window_event(event: str, data: dict[str, Any]) → None

Handle a window event from the browser.

This is called internally by the server.

Parameters:

• event – The event type (‘resize’, ‘close’).

• data – Event-specific data.

property height: int | None

Get the current window height (None if browser default).

light() → Window

Switch to light theme.

Convenience method equivalent to set_theme(“light”).

Returns:

Self for method chaining.

Examples

>>> app.window.light()

on_close(callback: Callable[[], None]) → Window

Register a callback for window close events.

Parameters:

callback – Function called when the window is about to close.

Returns:

Self for method chaining.

Examples

>>> def handle_close():
...     print("Window closing!")
>>> app.window.on_close(handle_close)

on_resize(callback: Callable[[int, int], None]) → Window

Register a callback for window resize events.

Parameters:

callback – Function that receives (width, height) when window resizes.

Returns:

Self for method chaining.

Examples

>>> def handle_resize(width, height):
...     print(f"Window resized to {width}x{height}")
>>> app.window.on_resize(handle_resize)

resize(width: int, height: int) → Window

Resize the browser window.

Note: Some browsers may restrict window resizing for security.

Parameters:

• width – The new width in pixels.

• height – The new height in pixels.

Returns:

Self for method chaining.

Examples

>>> app.window.resize(1280, 720)

set_background(color: str) → Window

Set the page background color.

Parameters:

color – CSS color value (e.g., ‘#ffffff’, ‘rgb(0,0,0)’, ‘white’).

Returns:

Self for method chaining.

Examples

>>> app.window.set_background("#1a1a2e")

set_favicon(url: str) → Window

Set the page favicon.

Parameters:

url – URL to the favicon image.

Returns:

Self for method chaining.

Examples

>>> app.window.set_favicon("/static/icon.png")

set_theme(theme: str) → Window

Set the color theme.

Parameters:

theme – The theme to use (‘light’, ‘dark’, or ‘auto’).

Returns:

Self for method chaining.

Examples

>>> app.window.set_theme("dark")

set_title(title: str) → Window

Set the window title.

Updates the browser tab title in real-time.

Parameters:

title – The new window title.

Returns:

Self for method chaining.

Examples

>>> app.window.set_title("Processing... 50%")

property theme: str

Get the current theme (‘light’, ‘dark’, or ‘auto’).

property title: str

Get the current window title.

property width: int | None

Get the current window width (None if browser default).

class animaid.WindowConfig(title: str = 'AnimAID', width: int | None = None, height: int | None = None, theme: str = 'light', background_color: str = '#fafafa', favicon: str | None = None)

Bases: object

Configuration for window initialization.

Use this to configure the initial state of the browser window when creating an App.

Examples

>>> from animaid import App, WindowConfig
>>> # Use a preset for quick setup
>>> config = WindowConfig.compact(title="My Tool")
>>> with App(window=config) as app:
...     app.add(HTMLString("Hello"))

>>> # Or configure manually
>>> config = WindowConfig(
...     title="Dashboard",
...     width=1280,
...     height=720,
...     theme="dark"
... )

background_color: str = '#fafafa'

classmethod compact(title: str = 'AnimAID') → WindowConfig

Create a compact window configuration (600x400).

Parameters:

title – The window title.

Returns:

A WindowConfig for a small, compact window.

classmethod dark(title: str = 'AnimAID') → WindowConfig

Create a dark-themed window configuration.

Parameters:

title – The window title.

Returns:

A WindowConfig with dark theme.

favicon: str | None = None

height: int | None = None

classmethod standard(title: str = 'AnimAID') → WindowConfig

Create a standard window configuration (1024x768).

Parameters:

title – The window title.

Returns:

A WindowConfig for a standard-sized window.

theme: str = 'light'

title: str = 'AnimAID'

classmethod wide(title: str = 'AnimAID') → WindowConfig

Create a wide window configuration (1280x720).

Parameters:

title – The window title.

Returns:

9. window.

Return type:

A WindowConfig for a wide (16

width: int | None = None

animaid.h_dict

alias of HTMLDict

animaid.h_float

alias of HTMLFloat

animaid.h_int

alias of HTMLInt

animaid.h_list

alias of HTMLList

animaid.h_set

alias of HTMLSet

animaid.h_string

alias of HTMLString

animaid.h_tuple

alias of HTMLTuple

Interactive Display

App

class animaid.App(port: int = 8200, title: str = 'AnimAID', auto_open: bool = True, window: WindowConfig | None = None, width: int | None = None, height: int | None = None, theme: str = 'light')

Bases: object

A Tkinter-like interactive GUI environment using HTML.

The browser becomes the display surface, and AnimAID objects become widgets that can be added, updated, and removed programmatically with real-time visual feedback.

Examples

>>> from animaid import App, HTMLString
>>> app = App()
>>> app.run()  # Starts server, opens browser
>>> app.add(HTMLString("Hello").bold)
'string_1'
>>> app.add(HTMLString("World").italic)
'string_2'
>>> app.stop()

# Context manager support >>> with App() as app: … app.add(HTMLString(“Temporary display”)) # Server stops when context exits

# With window configuration >>> with App(title=”Dashboard”, theme=”dark”) as app: … app.window.set_title(“Loading…”) … app.add(HTMLString(“Content”))

Note

The class was previously named Animate. That name still works but is deprecated. Please use App instead.

add(item: HTMLObject | str, id: str | None = None) → str

Add an item to the display.

Parameters:

• item – An HTMLObject or string to display.

• id – Optional custom ID for the item. Auto-generated if not provided.

Returns:

The ID of the added item.

clear(item_or_id: HTMLObject | str) → bool

Remove an item by ID or by object reference.

Parameters:

item_or_id – The ID of the item to remove, or the item object itself.

Returns:

True if the item was found and removed, False otherwise.

clear_all() → None

Remove all items from the display.

get(id: str) → Any

Get an item by ID.

Parameters:

id – The ID of the item to retrieve.

Returns:

The item if found, None otherwise.

get_events() → list[InputEvent]

Get all pending events without blocking.

Returns:

A list of all pending InputEvent objects. Empty list if none.

Examples

>>> events = anim.get_events()
>>> for event in events:
...     print(f"Event: {event.event_type} on {event.id}")

get_full_state() → list[dict[str, str]]

Get the full state as a list of rendered items.

Returns:

…, “html”: …} dicts.

Return type:

A list of {“id”

handle_input_event(message: dict[str, Any]) → None

Handle an input event from the browser.

This is called by the server when an input event is received. It updates the item’s internal value, calls registered callbacks, and queues the event for polling.

Parameters:

message – The event message containing id, event type, and value.

handle_window_event(message: dict[str, Any]) → None

Handle a window event from the browser.

This is called by the server when a window event is received.

Parameters:

message – The event message containing event type and data.

property is_running: bool

Check if the server is running.

items() → list[tuple[str, Any]]

Get a copy of all items.

Returns:

A list of (id, item) tuples.

property port: int

Get the server port.

refresh(id: str) → bool

Re-render and broadcast a single item.

Use this to manually refresh an item after external changes.

Parameters:

id – The ID of the item to refresh.

Returns:

True if item was found and refreshed, False otherwise.

refresh_all() → None

Re-render and broadcast all items.

Use this to manually refresh all items after external changes.

register_connection(websocket: Any) → None

Register a WebSocket connection.

This is called by the server when a new client connects.

Parameters:

websocket – The WebSocket connection to register.

remove(item_or_id: HTMLObject | str) → bool

Remove an item by ID or by object reference.

Parameters:

item_or_id – The ID of the item to remove, or the item object itself.

Returns:

True if the item was found and removed, False otherwise.

run() → App

Start the server in a background thread and open the browser.

Returns:

Self for method chaining.

stop() → None

Stop the server.

property title: str

Get the display title.

unregister_connection(websocket: Any) → None

Unregister a WebSocket connection.

This is called by the server when a client disconnects.

Parameters:

websocket – The WebSocket connection to unregister.

update(id: str, item: HTMLObject | str) → bool

Update an existing item by ID.

Parameters:

• id – The ID of the item to update.

• item – The new content to display.

Returns:

True if the item was found and updated, False otherwise.

property url: str

Get the server URL.

wait_for_event(timeout: float | None = None) → InputEvent | None

Block until an input event occurs.

Parameters:

timeout – Maximum time to wait in seconds. None means wait forever.

Returns:

The InputEvent if one occurred, None if timeout expired.

Examples

>>> event = anim.wait_for_event(timeout=1.0)
>>> if event and event.event_type == "click":
...     print(f"Button {event.id} was clicked!")

property window: Window

Access window-level controls.

Returns:

The Window instance for controlling window appearance and behavior.

Examples

>>> app.window.dark()  # Switch to dark theme
>>> app.window.set_title("Processing...")

HTML Types

HTMLString

class animaid.HTMLString(content: str = '', **styles: str | CSSValue)

Bases: HTMLObject, str

A string subclass that renders as styled HTML.

HTMLString behaves like a regular Python string but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining.

Examples

>>> s = HTMLString("Hello World")
>>> s.bold().color("red").render()
'<span style="font-weight: bold; color: red">Hello World</span>'

>>> s = HTMLString("Click me", color="blue", text_decoration="underline")
>>> s.render()
'<span style="color: blue; text-decoration: underline">Click me</span>'

add_class(*class_names: str) → Self

Add CSS classes in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

Example

>>> s = HTMLString("Hello").add_class("highlight", "important")
>>> s.render()
'<span class="highlight important">Hello</span>'

background(value: Color | str) → Self

Apply specified background color in-place.

Parameters:

value – CSS color value (e.g., “yellow”, Color.yellow)

badge() → Self

Apply badge/pill style in-place.

bg_black() → Self

Apply black background in-place.

bg_blue() → Self

Apply blue background in-place.

bg_gray() → Self

Apply gray background in-place.

bg_green() → Self

Apply green background in-place.

bg_orange() → Self

Apply orange background in-place.

bg_pink() → Self

Apply pink background in-place.

bg_purple() → Self

Apply purple background in-place.

bg_red() → Self

Apply red background in-place.

bg_white() → Self

Apply white background in-place.

bg_yellow() → Self

Apply yellow background in-place.

black() → Self

Apply black text color in-place.

blue() → Self

Apply blue text color in-place.

bold() → Self

Apply bold text style in-place.

border(value: Border | str) → Self

Apply specified border in-place.

Parameters:

value – CSS border value (e.g., “1px solid black”, Border.solid())

border_radius(value: Size | str | int | float) → Self

Apply specified border radius in-place.

Parameters:

value – CSS border-radius value (e.g., “5px”, Size.px(5), Size.percent(50))

capitalize() → Self

Apply capitalize text transform in-place.

code() → Self

Apply inline code style in-place.

color(value: Color | str) → Self

Apply specified text color in-place.

Parameters:

value – CSS color value (e.g., “red”, “#ff0000”, Color.red)

display(value: Display | str) → Self

Apply specified display mode in-place.

Parameters:

value – CSS display value (e.g., “block”, “flex”, Display.FLEX)

error() → Self

Apply error style (red) in-place.

font_family(value: str) → Self

Apply specified font family in-place.

Parameters:

value – CSS font-family value.

font_size(value: Size | str | int | float) → Self

Apply specified font size in-place.

Parameters:

value – CSS size value (e.g., “16px”, Size.px(16), Size.em(1.2))

gray() → Self

Apply gray text color in-place.

green() → Self

Apply green text color in-place.

height(value: Size | str | int | float) → Self

Apply specified height in-place.

Parameters:

value – CSS height value (e.g., “50px”, Size.px(50), Size.vh(100))

highlight() → Self

Apply highlight style (yellow background) in-place.

info() → Self

Apply info style (blue) in-place.

italic() → Self

Apply italic text style in-place.

large() → Self

Apply large text size (20px) in-place.

link() → Self

Apply link style in-place.

lowercase() → Self

Apply lowercase text transform in-place.

margin(value: Spacing | str | int | float) → Self

Apply specified margin in-place.

Parameters:

value – CSS margin value (e.g., “10px”, Size.px(10), Spacing.all(10))

medium() → Self

Apply medium text size (16px) in-place.

monospace() → Self

Apply monospace font in-place.

muted() → Self

Apply muted/secondary text style in-place.

nowrap() → Self

Apply nowrap white-space style in-place.

opacity(value: str | float) → Self

Apply specified opacity in-place.

Parameters:

value – CSS opacity value (0.0 to 1.0)

orange() → Self

Apply orange text color in-place.

padding(value: Spacing | str | int | float) → Self

Apply specified padding in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10))

pink() → Self

Apply pink text color in-place.

purple() → Self

Apply purple text color in-place.

red() → Self

Apply red text color in-place.

render() → str

Return HTML representation of this string.

The string content is HTML-escaped to prevent XSS.

Returns:

A string containing valid HTML.

Example

>>> HTMLString("<script>alert('xss')</script>").render()
'<span>&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;</span>'

small() → Self

Apply small text size (14px) in-place.

strikethrough() → Self

Apply strikethrough text style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional inline styles in-place.

Style names use Python convention (underscores) and are converted to CSS convention (hyphens) automatically.

Parameters:

**styles – CSS property-value pairs. Accepts strings and CSS types. e.g., font_size=”16px” or font_size=Size.px(16)

Returns:

Self for method chaining.

Example

>>> s = HTMLString("Hello").styled(color="red", font_size="20px")
>>> s.render()
'<span style="color: red; font-size: 20px">Hello</span>'

>>> s = HTMLString("Hello").styled(color=Color.red, font_size=Size.px(20))
>>> s.render()
'<span style="color: red; font-size: 20px">Hello</span>'

success() → Self

Apply success style (green) in-place.

tag(tag_name: str) → Self

Change the HTML tag in-place.

Parameters:

tag_name – The HTML tag to use (e.g., “div”, “p”, “strong”).

Returns:

Self for method chaining.

Example

>>> s = HTMLString("Hello").tag("strong").render()
'<strong>Hello</strong>'

underline() → Self

Apply underline text style in-place.

uppercase() → Self

Apply uppercase text transform in-place.

warning() → Self

Apply warning style (orange) in-place.

white() → Self

Apply white text color in-place.

width(value: Size | str | int | float) → Self

Apply specified width in-place.

Parameters:

value – CSS width value (e.g., “100px”, Size.px(100), Size.percent(50))

xl() → Self

Apply extra-large text size (24px) in-place.

xs() → Self

Apply extra-small text size (12px) in-place.

xxl() → Self

Apply 2x extra-large text size (32px) in-place.

yellow() → Self

Apply yellow text color in-place.

HTMLList

class animaid.HTMLList(items: list[Any] | None = None, **styles: str | CSSValue)

Bases: HTMLObject, list

A list subclass that renders as styled HTML.

HTMLList behaves like a regular Python list but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining. Supports vertical, horizontal, and grid layouts.

Examples

>>> items = HTMLList(["Apple", "Banana", "Cherry"])
>>> items.render()
'<ul><li>Apple</li><li>Banana</li><li>Cherry</li></ul>'

>>> items.horizontal().gap("10px").render()
'<div style="display: flex; flex-direction: row; gap: 10px">...</div>'

>>> HTMLList([1, 2, 3]).ordered().render()
'<ol><li>1</li><li>2</li><li>3</li></ol>'

add_class(*class_names: str) → Self

Add CSS classes on the container in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

add_item_class(*class_names: str) → Self

Add CSS classes to each item in-place.

Parameters:

*class_names – CSS class names to add to items.

align_items(value: AlignItems | str) → Self

Apply specified cross-axis alignment in-place.

Parameters:

value – CSS align-items value (e.g., “center”, AlignItems.CENTER).

append(item: Any) → None

Append item, notifying observers.

background(value: Color | str) → Self

Apply background color on the container in-place.

Parameters:

value – CSS color value (e.g., “white”, Color.white, Color.hex(“#fff”)).

border(value: Border | str) → Self

Apply border around the container in-place.

Parameters:

value – CSS border value (e.g., “1px solid black”, Border.solid()).

border_radius(value: Size | str | int | float) → Self

Apply rounded corners on the container in-place.

Parameters:

value – CSS border-radius value (e.g., “5px”, Size.px(5)).

bulleted() → Self

Apply bulleted list style in-place.

cards() → Self

Apply card list style with shadows and spacing in-place.

Creates a visually appealing list where each item looks like a card.

center() → Self

Apply centered alignment on both axes in-place.

clear() → None

Clear list, notifying observers.

color(value: Color | str) → Self

Apply text color in-place.

Parameters:

value – CSS color value (e.g., “black”, Color.black).

compact() → Self

Apply minimal spacing style in-place.

extend(items: Any) → None

Extend list, notifying observers.

gap(value: Size | str | int | float) → Self

Apply specified gap between items in-place.

Parameters:

value – CSS gap value (e.g., “10px”, Size.px(10), Size.rem(1)).

grid(columns: int = 3) → Self

Apply CSS grid layout in-place.

Parameters:

columns – Number of columns in the grid.

Returns:

Self for method chaining.

height(value: Size | str | int | float) → Self

Apply specified height in-place.

Parameters:

value – CSS height value (e.g., “200px”, Size.px(200), Size.vh(100)).

horizontal() → Self

Apply horizontal layout in-place.

Items are arranged left to right using flexbox.

horizontal_reverse() → Self

Apply reversed horizontal layout in-place.

Items are arranged right to left.

inline() → Self

Apply inline style in-place.

Creates a simple inline list separated by spacing.

insert(index: Any, item: Any) → None

Insert item, notifying observers.

item_background(value: Color | str) → Self

Apply background color on each item in-place.

Parameters:

value – CSS color value.

item_border(value: Border | str) → Self

Apply border around each item in-place.

Parameters:

value – CSS border value for items.

item_border_radius(value: Size | str | int | float) → Self

Apply rounded corners on each item in-place.

Parameters:

value – CSS border-radius value for items.

item_margin(value: Spacing | str | int | float) → Self

Apply margin around each item in-place.

Parameters:

value – CSS margin value for items.

item_padding(value: Spacing | str | int | float) → Self

Apply padding inside each item in-place.

Parameters:

value – CSS padding value for items.

justify_content(value: JustifyContent | str) → Self

Apply specified main-axis alignment in-place.

Parameters:

value – CSS justify-content value (e.g., “space-between”).

margin(value: Spacing | str | int | float) → Self

Apply margin outside the container in-place.

Parameters:

value – CSS margin value (e.g., “10px”, Size.px(10), Spacing.all(10)).

max_width(value: Size | str | int | float) → Self

Apply maximum width constraint in-place.

Parameters:

value – CSS max-width value (e.g., “800px”, Size.px(800)).

menu() → Self

Apply vertical menu style in-place.

Creates a clean vertical menu suitable for navigation.

numbered() → Self

Apply numbered list style in-place.

ordered() → Self

Apply ordered list (<ol>) format in-place.

padding(value: Spacing | str | int | float) → Self

Apply padding inside the container in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10)).

pills() → Self

Apply pill/badge style in-place.

Creates a horizontal list of pill-shaped items.

plain() → Self

Apply plain div container (no bullets/numbers) in-place.

pop(index: Any = -1) → Any

Pop item, notifying observers.

remove(item: Any) → None

Remove item, notifying observers.

render() → str

Return HTML representation of this list.

Returns:

A string containing valid HTML.

reverse() → None

Reverse list, notifying observers.

separator(value: Border | str) → Self

Apply separator lines between items in-place.

Unlike item_border, this only adds borders between items, not on the outer edges.

Parameters:

value – CSS border value for separators.

sort(*, key: Any = None, reverse: bool = False) → None

Sort list, notifying observers.

spaced() → Self

Apply generous spacing style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional container styles in-place.

Parameters:

**styles – CSS property-value pairs for the container. Accepts both strings and CSS type objects (Color, Size, etc.)

Returns:

Self for method chaining.

tags() → Self

Apply tags/labels style in-place.

Creates a horizontal list of tag-style items.

unordered() → Self

Apply unordered list (<ul>) format in-place.

vertical() → Self

Apply vertical layout (default) in-place.

Items are stacked top to bottom.

vertical_reverse() → Self

Apply reversed vertical layout in-place.

Items are stacked bottom to top.

width(value: Size | str | int | float) → Self

Apply specified width in-place.

Parameters:

value – CSS width value (e.g., “100px”, Size.px(100), Size.percent(50)).

HTMLDict

class animaid.HTMLDict(data: dict[Any, Any] | None = None, **styles: str | CSSValue)

Bases: HTMLObject, dict

A dict subclass that renders as styled HTML.

HTMLDict behaves like a regular Python dict but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining. Supports definition list, table, and flexbox layouts.

Examples

>>> d = HTMLDict({"name": "Alice", "age": 30})
>>> d.render()
'<dl><dt>name</dt><dd>Alice</dd><dt>age</dt><dd>30</dd></dl>'

>>> d.as_table().render()
'<table><tr><td>name</td><td>Alice</td></tr>...</table>'

>>> d.key_bold().key_color("blue").render()
'<dl><dt style="font-weight: bold; color: blue">name</dt>...'

add_class(*class_names: str) → Self

Add CSS classes on the container in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

add_key_class(*class_names: str) → Self

Add CSS classes to keys in-place.

Parameters:

*class_names – CSS class names to add to keys.

add_value_class(*class_names: str) → Self

Add CSS classes to values in-place.

Parameters:

*class_names – CSS class names to add to values.

as_definition_list() → Self

Apply definition list (<dl>) format in-place.

as_divs() → Self

Apply flexbox divs format in-place.

as_table() → Self

Apply table (<table>) format in-place.

background(value: Color | str) → Self

Apply container background in-place.

Parameters:

value – CSS color value (e.g., “white”, Color.white, Color.hex(“#fff”)).

border(value: Border | str) → Self

Apply container border in-place.

Parameters:

value – CSS border value (e.g., “1px solid black”, Border.solid()).

border_radius(value: Size | str | int | float) → Self

Apply rounded container corners in-place.

Parameters:

value – CSS border-radius value (e.g., “5px”, Size.px(5), Size.percent(50)).

bordered() → Self

Apply bordered cells style in-place.

Each key-value pair has visible borders.

card() → Self

Apply card style with shadow and rounded corners in-place.

Creates a visually appealing card-style display.

clear() → None

Clear dict, notifying observers.

color(value: Color | str) → Self

Apply text color in-place.

Parameters:

value – CSS color value (e.g., “black”, Color.black).

compact() → Self

Apply compact spacing style in-place.

Minimal padding and spacing for dense displays.

entry_separator(value: Border | str) → Self

Apply separator between entries (border) in-place.

Parameters:

value – CSS border value for separator (e.g., “1px solid gray”).

gap(value: Size | str | int | float) → Self

Apply gap between entries in-place.

Parameters:

value – CSS gap value (e.g., “10px”, Size.px(10), Size.rem(1)).

grid(columns: int = 2) → Self

Apply grid layout in-place.

Parameters:

columns – Number of key-value pairs per row.

hide_keys() → Self

Hide keys and only render values in-place.

horizontal() → Self

Apply horizontal layout (entries side by side) in-place.

inline() → Self

Apply inline horizontal display in-place.

All key-value pairs on one line.

key_background(value: Color | str) → Self

Apply background color to keys in-place.

Parameters:

value – CSS color value (e.g., “yellow”, Color.yellow).

key_bold() → Self

Apply bold style to keys in-place.

key_color(value: Color | str) → Self

Apply color to keys in-place.

Parameters:

value – CSS color value (e.g., “blue”, Color.blue, Color.hex(“#00f”)).

key_italic() → Self

Apply italic style to keys in-place.

key_padding(value: Spacing | str | int | float) → Self

Apply padding to keys in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10), Spacing.all(10)).

key_styled(**styles: str | CSSValue) → Self

Apply styles to keys in-place.

Parameters:

**styles – CSS property-value pairs for keys. Accepts both strings and CSS type objects (Color, Size, etc.)

key_width(value: Size | str | int | float) → Self

Apply fixed key width in-place.

Parameters:

value – CSS width value (e.g., “100px”, Size.px(100)).

labeled() → Self

Apply label-style keys in-place.

Keys are styled as small labels above values.

margin(value: Spacing | str | int | float) → Self

Apply container margin in-place.

Parameters:

value – CSS margin value (e.g., “10px”, Size.px(10), Spacing.all(10)).

max_width(value: Size | str | int | float) → Self

Apply maximum width in-place.

Parameters:

value – CSS max-width value (e.g., “500px”, Size.px(500), Size.vw(80)).

padding(value: Spacing | str | int | float) → Self

Apply container padding in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10)).

pop(key: Any, *default: Any) → Any

Pop item, notifying observers.

popitem() → tuple[Any, Any]

Pop item, notifying observers.

render() → str

Return HTML representation of this dictionary.

Returns:

A string containing valid HTML.

separator(value: str) → Self

Apply a separator between key and value in-place.

Parameters:

value – Separator string (e.g., “:”, “ -> “, “ = “).

setdefault(key: Any, default: Any = None) → Any

Set default, notifying observers.

simple() → Self

Apply simple key: value formatting in-place.

Clean, minimal display with colon separators.

spaced() → Self

Apply generous spacing style in-place.

More padding and gaps for readability.

striped() → Self

Apply striped table style in-place.

Creates an alternating row colors table.

styled(**styles: str | CSSValue) → Self

Apply additional container styles in-place.

Parameters:

**styles – CSS property-value pairs for the container. Accepts both strings and CSS type objects (Color, Size, etc.)

Returns:

Self for method chaining.

update(*args: Any, **kwargs: Any) → None

Update dict, notifying observers.

value_background(value: Color | str) → Self

Apply background color to values in-place.

Parameters:

value – CSS color value (e.g., “lightgray”, Color.hex(“#eee”)).

value_bold() → Self

Apply bold style to values in-place.

value_color(value: Color | str) → Self

Apply color to values in-place.

Parameters:

value – CSS color value (e.g., “green”, Color.green).

value_italic() → Self

Apply italic style to values in-place.

value_padding(value: Spacing | str | int | float) → Self

Apply padding to values in-place.

Parameters:

value – CSS padding value (e.g., “10px”, Size.px(10), Spacing.all(10)).

value_styled(**styles: str | CSSValue) → Self

Apply styles to values in-place.

Parameters:

**styles – CSS property-value pairs for values. Accepts both strings and CSS type objects (Color, Size, etc.)

vertical() → Self

Apply vertical layout (entries stacked) in-place.

width(value: Size | str | int | float) → Self

Apply container width in-place.

Parameters:

value – CSS width value (e.g., “300px”, Size.px(300), Size.percent(100)).

HTMLSet

class animaid.HTMLSet(items: Iterable[Any] = (), **styles: str | CSSValue)

Bases: HTMLObject, set

A set subclass that renders as styled HTML.

HTMLSet behaves like a regular Python set but includes methods for applying CSS styles and rendering to HTML. All styling methods modify the object in-place and return self for method chaining. Items are automatically deduplicated (set behavior). Mutations trigger notifications for reactive updates.

Examples

>>> s = HTMLSet({1, 2, 3})
>>> s.render()
'<span>{1, 2, 3}</span>'

>>> s.horizontal().pills().render()
'<div style="display: flex; ...">...</div>'

>>> HTMLSet([1, 1, 2, 2, 3])  # Duplicates removed
HTMLSet({1, 2, 3})

add(item: Any) → None

Add item, notifying observers.

add_class(*class_names: str) → Self

Add CSS classes on the container in-place.

Parameters:

*class_names – CSS class names to add.

Returns:

Self for method chaining.

add_item_class(*class_names: str) → Self

Add CSS classes to each item in-place.

align_items(value: AlignItems | str) → Self

Apply specified cross-axis alignment in-place.

background(value: Color | str) → Self

Apply background color on the container in-place.

border(value: Border | str) → Self

Apply border around the container in-place.

border_radius(value: Size | str | int | float) → Self

Apply rounded corners on the container in-place.

braces() → Self

Apply braces format (default) in-place.

center() → Self

Apply centered alignment on both axes in-place.

clear() → None

Clear set, notifying observers.

color(value: Color | str) → Self

Apply text color in-place.

compact() → Self

Apply minimal spacing style in-place.

difference(*others: Iterable[Any]) → Self

Return difference with other sets, preserving settings.

difference_update(*others: Iterable[Any]) → None

Difference update, notifying observers.

discard(item: Any) → None

Discard item, notifying observers.

gap(value: Size | str | int | float) → Self

Apply specified gap between items in-place.

grid(columns: int = 3) → Self

Apply CSS grid layout in-place.

Parameters:

columns – Number of columns in the grid.

height(value: Size | str | int | float) → Self

Apply specified height in-place.

horizontal() → Self

Apply horizontal layout (default) in-place.

horizontal_reverse() → Self

Apply reversed horizontal layout in-place.

inline() → Self

Apply inline style in-place.

intersection(*others: Iterable[Any]) → Self

Return intersection with other sets, preserving settings.

intersection_update(*others: Iterable[Any]) → None

Intersection update, notifying observers.

item_background(value: Color | str) → Self

Apply background color on each item in-place.

item_border(value: Border | str) → Self

Apply border around each item in-place.

item_border_radius(value: Size | str | int | float) → Self

Apply rounded corners on each item in-place.

item_margin(value: Spacing | str | int | float) → Self

Apply margin around each item in-place.

item_padding(value: Spacing | str | int | float) → Self

Apply padding inside each item in-place.

justify_content(value: JustifyContent | str) → Self

Apply specified main-axis alignment in-place.

margin(value: Spacing | str | int | float) → Self

Apply margin outside the container in-place.

padding(value: Spacing | str | int | float) → Self

Apply padding inside the container in-place.

pills() → Self

Apply pill/badge style in-place.

plain() → Self

Apply plain format (without brace decoration) in-place.

pop() → Any

Pop item, notifying observers.

remove(item: Any) → None

Remove item, notifying observers.

render() → str

Return HTML representation of this set.

Returns:

A string containing valid HTML.

separator(value: Border | str) → Self

Apply separator lines between items in-place.

sorted() → Self

Apply sorted rendering order in-place.

spaced() → Self

Apply generous spacing style in-place.

styled(**styles: str | CSSValue) → Self

Apply additional container styles in-place.

Parameters:

**styles – CSS property-value pairs for the container.

Returns:

Self for method chaining.

symmetric_difference(other: Iterable[Any]) → Self

Return symmetric difference with other set, preserving settings.

symmetric_difference_update(other: Iterable[Any]) → None

Symmetric difference update, notifying observers.

tags() → Self

Apply tags/labels style in-place.

union(*others: Iterable[Any]) → Self

Return union with other sets, preserving settings.

unsorted() → Self

Apply iteration order (no sorting) in-place.

update(*others: Iterable[Any]) → None

Update set, notifying observers.

vertical() → Self

Apply vertical layout in-place.

vertical_reverse() → Self

Apply reversed vertical layout in-place.

width(value: Size | str | int | float) → Self

Apply specified width in-place.

CSS Types

Size

class animaid.Size(value: float | str, unit: str = '')

Bases: CSSValue

Represents a CSS size/length value with units.

Examples

>>> Size.px(10)
Size('10px')
>>> Size.em(1.5)
Size('1.5em')
>>> Size.percent(50)
Size('50%')
>>> Size.auto()
Size('auto')

KEYWORDS: ClassVar[set[str]] = {'auto', 'fit-content', 'inherit', 'initial', 'max-content', 'min-content', 'none', 'unset'}

VALID_UNITS: ClassVar[set[str]] = {'%', 'ch', 'cm', 'em', 'ex', 'fr', 'in', 'mm', 'pc', 'pt', 'px', 'rem', 'vh', 'vmax', 'vmin', 'vw'}

classmethod auto() → Size

Create an ‘auto’ size.

classmethod em(value: float) → Size

Create an em size.

classmethod fr(value: float) → Size

Create a fractional unit size (for CSS grid).

classmethod full() → Size

Create a full width/height (100%).

classmethod half() → Size

Create a half width/height (50%).

classmethod inherit() → Size

Create an ‘inherit’ size.

property is_keyword: bool

True if this is a keyword value like ‘auto’.

classmethod lg() → Size

Create a large size (24px).

classmethod md() → Size

Create a medium size (16px).

classmethod none() → Size

Create a ‘none’ size.

classmethod percent(value: float) → Size

Create a percentage size.

classmethod px(value: float) → Size

Create a pixel size.

classmethod quarter() → Size

Create a quarter width/height (25%).

classmethod rem(value: float) → Size

Create a rem size.

classmethod sm() → Size

Create a small size (8px).

classmethod third() → Size

Create a third width/height (33.333%).

to_css() → str

Return the CSS string representation.

property unit: str

The unit string.

property value: float | None

The numeric value, or None for keywords.

classmethod vh(value: float) → Size

Create a viewport height size.

classmethod vw(value: float) → Size

Create a viewport width size.

classmethod xl() → Size

Create an extra-large size (32px).

classmethod xs() → Size

Create an extra-small size (4px).

classmethod xxl() → Size

Create a 2x extra-large size (48px).

classmethod zero() → Size

Create a zero size (0px).

Color

class animaid.Color(value: str)

Bases: CSSValue

Represents a CSS color value.

Supports named colors, hex codes, rgb(), rgba(), hsl(), and hsla().

Examples

>>> Color.red
Color('red')
>>> Color.hex("#2563eb")
Color('#2563eb')
>>> Color.rgb(255, 128, 0)
Color('rgb(255, 128, 0)')
>>> Color.rgba(255, 128, 0, 0.5)
Color('rgba(255, 128, 0, 0.5)')

NAMED_COLORS: ClassVar[set[str]] = {'aqua', 'black', 'blue', 'brown', 'currentcolor', 'cyan', 'fuchsia', 'gray', 'green', 'grey', 'inherit', 'initial', 'lime', 'magenta', 'maroon', 'navy', 'olive', 'orange', 'pink', 'purple', 'red', 'silver', 'teal', 'transparent', 'unset', 'white', 'yellow'}

aqua: ClassVar[Color] = Color('aqua')

black: ClassVar[Color] = Color('black')

blue: ClassVar[Color] = Color('blue')

brown: ClassVar[Color] = Color('brown')

cyan: ClassVar[Color] = Color('cyan')

dark_gray: ClassVar[Color] = Color('#374151')

error: ClassVar[Color] = Color('#ef4444')

gray: ClassVar[Color] = Color('gray')

green: ClassVar[Color] = Color('green')

grey: ClassVar[Color] = Color('grey')

classmethod hex(code: str) → Color

Create a color from a hex code.

Parameters:

code – Hex code with or without ‘#’ prefix

classmethod hsl(h: int, s: int, lightness: int) → Color

Create an HSL color.

Parameters:

• h – Hue (0-360)

• s – Saturation (0-100)

• lightness – Lightness (0-100)

classmethod hsla(h: int, s: int, lightness: int, a: float) → Color

Create an HSLA color with alpha.

Parameters:

• h – Hue (0-360)

• s – Saturation (0-100)

• lightness – Lightness (0-100)

• a – Alpha (0.0-1.0)

info: ClassVar[Color] = Color('#3b82f6')

light_gray: ClassVar[Color] = Color('#f5f5f5')

lime: ClassVar[Color] = Color('lime')

magenta: ClassVar[Color] = Color('magenta')

maroon: ClassVar[Color] = Color('maroon')

muted: ClassVar[Color] = Color('#6b7280')

navy: ClassVar[Color] = Color('navy')

olive: ClassVar[Color] = Color('olive')

orange: ClassVar[Color] = Color('orange')

pink: ClassVar[Color] = Color('pink')

purple: ClassVar[Color] = Color('purple')

red: ClassVar[Color] = Color('red')

classmethod rgb(r: int, g: int, b: int) → Color

Create an RGB color.

Parameters:

• r – Red component (0-255)

• g – Green component (0-255)

• b – Blue component (0-255)

classmethod rgba(r: int, g: int, b: int, a: float) → Color

Create an RGBA color with alpha.

Parameters:

• r – Red component (0-255)

• g – Green component (0-255)

• b – Blue component (0-255)

• a – Alpha component (0.0-1.0)

silver: ClassVar[Color] = Color('silver')

success: ClassVar[Color] = Color('#22c55e')

teal: ClassVar[Color] = Color('teal')

to_css() → str

Return the CSS string representation.

transparent: ClassVar[Color] = Color('transparent')

warning: ClassVar[Color] = Color('#f59e0b')

white: ClassVar[Color] = Color('white')

yellow: ClassVar[Color] = Color('yellow')

Border

class animaid.Border(width: Size | str | int | float = '1px', style: BorderStyle | str = BorderStyle.SOLID, color: Color | str = 'black')

Bases: CSSValue

Represents a CSS border value (width + style + color).

Examples

>>> Border(Size.px(1), BorderStyle.SOLID, Color.black)
Border('1px solid black')
>>> Border.solid(2, "red")
Border('2px solid red')
>>> Border().width(Size.px(2)).dashed().color(Color.blue)
Border('2px dashed blue')

as_dashed() → Border

Return a new Border with dashed style.

as_dotted() → Border

Return a new Border with dotted style.

as_double() → Border

Return a new Border with double style.

as_none() → Border

Return a new Border with no style.

as_solid() → Border

Return a new Border with solid style.

color(c: Color | str) → Border

Return a new Border with the specified color.

property color_value: Color

The border color.

classmethod dashed(width: Size | str | int | float = 1, color: Color | str = 'black') → Border

Create a dashed border.

Parameters:

• width – Border width (default 1px)

• color – Border color (default black)

Examples

>>> Border.dashed()
Border('1px dashed black')
>>> Border.dashed(2, "blue")
Border('2px dashed blue')

classmethod dotted(width: Size | str | int | float = 1, color: Color | str = 'black') → Border

Create a dotted border.

Parameters:

• width – Border width (default 1px)

• color – Border color (default black)

Examples

>>> Border.dotted()
Border('1px dotted black')

classmethod double(width: Size | str | int | float = 3, color: Color | str = 'black') → Border

Create a double border.

Parameters:

• width – Border width (default 3px - minimum for double to show)

• color – Border color (default black)

Examples

>>> Border.double()
Border('3px double black')

classmethod medium(color: Color | str = 'black', style: BorderStyle | str = BorderStyle.SOLID) → Border

Create a medium border (2px).

Parameters:

• color – Border color (default black)

• style – Border style (default solid)

Examples

>>> Border.medium()
Border('2px solid black')

classmethod none() → Border

Create a border with no visible style.

Examples

>>> Border.none()
Border('1px none black')

classmethod solid(width: Size | str | int | float = 1, color: Color | str = 'black') → Border

Create a solid border.

Parameters:

• width – Border width (default 1px)

• color – Border color (default black)

Examples

>>> Border.solid()
Border('1px solid black')
>>> Border.solid(2, "red")
Border('2px solid red')

style(s: BorderStyle | str) → Border

Return a new Border with the specified style.

property style_value: BorderStyle

The border style.

classmethod thick(color: Color | str = 'black', style: BorderStyle | str = BorderStyle.SOLID) → Border

Create a thick border (4px).

Parameters:

• color – Border color (default black)

• style – Border style (default solid)

Examples

>>> Border.thick()
Border('4px solid black')
>>> Border.thick("navy")
Border('4px solid navy')

classmethod thin(color: Color | str = 'black', style: BorderStyle | str = BorderStyle.SOLID) → Border

Create a thin border (1px).

Parameters:

• color – Border color (default black)

• style – Border style (default solid)

Examples

>>> Border.thin()
Border('1px solid black')
>>> Border.thin("red")
Border('1px solid red')

to_css() → str

Return the CSS border shorthand.

width(w: Size | str | int | float) → Border

Return a new Border with the specified width.

property width_value: Size

The border width.

Spacing

class animaid.Spacing(top: Size | str | int | float, right: Size | str | int | float | None = None, bottom: Size | str | int | float | None = None, left: Size | str | int | float | None = None)

Bases: CSSValue

Represents CSS spacing (padding/margin) with 1-4 values.

Examples

>>> Spacing.all(Size.px(10))
Spacing('10px')
>>> Spacing.symmetric(Size.px(10), Size.px(20))
Spacing('10px 20px')
>>> Spacing.edges(Size.px(1), Size.px(2), Size.px(3), Size.px(4))
Spacing('1px 2px 3px 4px')

classmethod all(value: Size | str | int | float) → Spacing

Create uniform spacing on all sides.

property bottom: Size

Bottom spacing (same as top if not specified).

classmethod button() → Spacing

Create typical button padding (8px 16px).

classmethod card() → Spacing

Create typical card padding (16px).

classmethod compact() → Spacing

Create compact spacing (4px 8px).

classmethod edges(top: Size | str | int | float, right: Size | str | int | float, bottom: Size | str | int | float, left: Size | str | int | float) → Spacing

Create spacing with explicit values for all four edges.

classmethod horizontal(value: Size | str | int | float) → Spacing

Create horizontal-only spacing (left and right).

classmethod input() → Spacing

Create typical input field padding (8px 12px).

property left: Size

Left spacing (same as right if not specified).

classmethod lg() → Spacing

Create large spacing (24px).

classmethod md() → Spacing

Create medium spacing (16px).

classmethod relaxed() → Spacing

Create relaxed/generous spacing (16px 24px).

property right: Size

Right spacing (same as top if not specified).

classmethod section() → Spacing

Create typical section margins (24px top/bottom, 0 left/right).

classmethod sm() → Spacing

Create small spacing (8px).

classmethod symmetric(vertical: Size | str | int | float, horizontal: Size | str | int | float) → Spacing

Create symmetric spacing (vertical and horizontal).

to_css() → str

Return the CSS spacing value.

property top: Size

Top spacing.

classmethod vertical(value: Size | str | int | float) → Spacing

Create vertical-only spacing (top and bottom).

classmethod xl() → Spacing

Create extra-large spacing (32px).

classmethod xs() → Spacing

Create extra-small spacing (4px).

classmethod zero() → Spacing

Create zero spacing.

CSS Enums

Display

class animaid.Display(value)

Bases: Enum

CSS display values.

BLOCK = 'block'

CONTENTS = 'contents'

FLEX = 'flex'

GRID = 'grid'

INLINE = 'inline'

INLINE_BLOCK = 'inline-block'

INLINE_FLEX = 'inline-flex'

INLINE_GRID = 'inline-grid'

NONE = 'none'

to_css() → str

FlexDirection

class animaid.FlexDirection(value)

Bases: Enum

CSS flex-direction values.

COLUMN = 'column'

COLUMN_REVERSE = 'column-reverse'

ROW = 'row'

ROW_REVERSE = 'row-reverse'

to_css() → str

AlignItems

class animaid.AlignItems(value)

Bases: Enum

CSS align-items values.

BASELINE = 'baseline'

CENTER = 'center'

END = 'end'

FLEX_END = 'flex-end'

FLEX_START = 'flex-start'

START = 'start'

STRETCH = 'stretch'

to_css() → str

JustifyContent

class animaid.JustifyContent(value)

Bases: Enum

CSS justify-content values.

CENTER = 'center'

END = 'end'

FLEX_END = 'flex-end'

FLEX_START = 'flex-start'

SPACE_AROUND = 'space-around'

SPACE_BETWEEN = 'space-between'

SPACE_EVENLY = 'space-evenly'

START = 'start'

STRETCH = 'stretch'

to_css() → str

FontWeight

class animaid.FontWeight(value)

Bases: Enum

CSS font-weight values.

BOLD = 'bold'

BOLDER = 'bolder'

LIGHTER = 'lighter'

NORMAL = 'normal'

W100 = '100'

W200 = '200'

W300 = '300'

W400 = '400'

W500 = '500'

W600 = '600'

W700 = '700'

W800 = '800'

W900 = '900'

to_css() → str

Return the CSS value.

FontStyle

class animaid.FontStyle(value)

Bases: Enum

CSS font-style values.

ITALIC = 'italic'

NORMAL = 'normal'

OBLIQUE = 'oblique'

to_css() → str

TextAlign

class animaid.TextAlign(value)

Bases: Enum

CSS text-align values.

CENTER = 'center'

END = 'end'

JUSTIFY = 'justify'

LEFT = 'left'

RIGHT = 'right'

START = 'start'

to_css() → str

TextDecoration

class animaid.TextDecoration(value)

Bases: Enum

CSS text-decoration values.

LINE_THROUGH = 'line-through'

NONE = 'none'

OVERLINE = 'overline'

UNDERLINE = 'underline'

to_css() → str

BorderStyle

class animaid.BorderStyle(value)

Bases: Enum

CSS border-style values.

DASHED = 'dashed'

DOTTED = 'dotted'

DOUBLE = 'double'

GROOVE = 'groove'

HIDDEN = 'hidden'

INSET = 'inset'

NONE = 'none'

OUTSET = 'outset'

RIDGE = 'ridge'

SOLID = 'solid'

to_css() → str