htmforge 0.1.0

Type-safe, composable UI components for Python — server-side rendered, HTMX-first.

htmforge

Type-safe, composable UI components for Python — server-side rendered, HTMX-first, framework-agnostic.

Why htmforge?

• No templates — build HTML with plain Python classes and type-checked props
• HTMX-native — typed enums for every hx-* attribute, zero string guessing
• Pydantic validation — props are validated on construction and assignment
• Framework-agnostic — works with FastAPI, Flask, Django, or any WSGI/ASGI app

Installation

pip install htmforge

Quickstart

A FastAPI route that renders a full page with a user table and an add-user form:

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

from htmforge.components.page import Page
from htmforge.components import DataTable, FormField, InputType
from htmforge.core.element import Element
from htmforge.elements import div, h1

app = FastAPI()

USERS = [["Ada Lovelace", "[e-mail]"], ["Grace Hopper", "[e-mail]"]]


class UsersPage(Page):
    users: list[list[str]]
    added: bool = False

    def _body_content(self) -> list[Element | str | None]:
        return [
            div(
                h1("Users"),
                DataTable(
                    headers=["Name", "Email"],
                    rows=self.users,
                ),
                FormField(
                    name="name",
                    label_text="Full Name",
                    input_type=InputType.TEXT,
                    required=True,
                ),
            )
        ]


@app.get("/users", response_class=HTMLResponse)
def list_users() -> str:
    return UsersPage(
        title="Users",
        css_urls=["/static/style.css"],
        users=USERS,
    ).to_html()

Components

Component	Description	Import
DataTable	Table with optional HTMX reload	from htmforge.components import DataTable
Alert	Info/success/warning/error box, dismissible	from htmforge.components import Alert
Pagination	Previous/Next + page links with HTMX targeting	from htmforge.components import Pagination
Page	Full HTML document with DOCTYPE, abstract base	from htmforge.components.page import Page
FormField	Label + input + error div, 8 input types	from htmforge.components import FormField

HTMX Integration

All HTMX attributes are available as typed enums — no string typos:

from htmforge.elements import button
from htmforge.htmx import HxSwap, HxTarget, HxTrigger

btn = button(
    "Delete",
    hx_delete="/users/1",
    hx_swap=HxSwap.OUTER_HTML,
    hx_target=HxTarget.CLOSEST_TR,
    hx_confirm="Really delete?",
)
# → <button hx-delete="/users/1" hx-swap="outerHTML"
#           hx-target="closest tr" hx-confirm="Really delete?">Delete</button>

Framework Support

FastAPI

from fastapi.responses import HTMLResponse

@app.get("/", response_class=HTMLResponse)
def index() -> str:
    return MyPage(title="Home").to_html()

Flask

from flask import Response

@app.route("/")
def index() -> Response:
    return MyPage(title="Home").to_flask()

Django

from django.http import HttpRequest, HttpResponse

def index(request: HttpRequest) -> HttpResponse:
    return MyPage(title="Home").to_django()

Contributing

Contributions are welcome — please read CONTRIBUTING.md first.

License

MIT — see LICENSE.