# fh-matui


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## What is fh-matui?

**fh-matui** is a Python library that brings Google’s Material Design to
[FastHTML](https://fastht.ml/) applications. It provides a comprehensive
set of pre-built UI components that integrate seamlessly with FastHTML’s
hypermedia-driven architecture.

Built on top of [BeerCSS](https://www.beercss.com/) (a lightweight
Material Design 3 CSS framework), fh-matui enables you to create modern,
responsive web interfaces entirely in Python — no JavaScript required.

## ✨ Key Features

<table>
<colgroup>
<col style="width: 40%" />
<col style="width: 59%" />
</colgroup>
<thead>
<tr>
<th>Feature</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>🎨 <strong>Material Design 3</strong></td>
<td>Modern, beautiful components following Google’s latest design
language</td>
</tr>
<tr>
<td>⚡ <strong>Zero JavaScript</strong></td>
<td>Build interactive UIs entirely in Python with FastHTML</td>
</tr>
<tr>
<td>📱 <strong>Responsive</strong></td>
<td>Mobile-first design with automatic breakpoint handling</td>
</tr>
<tr>
<td>🌙 <strong>Dark Mode</strong></td>
<td>Built-in light/dark theme support with 20+ color schemes</td>
</tr>
<tr>
<td>🧩 <strong>Composable</strong></td>
<td>Chainable styling APIs inspired by MonsterUI</td>
</tr>
<tr>
<td>📊 <strong>Data Tables</strong></td>
<td>Full-featured tables with pagination, search, sorting, and CRUD</td>
</tr>
<tr>
<td>🔧 <strong>nbdev-powered</strong></td>
<td>Literate programming with documentation built from notebooks</td>
</tr>
</tbody>
</table>

## 🏗️ Architecture

    ┌─────────────────────────────────────────────────────────────┐
    │                        fh-matui                              │
    ├─────────────────────────────────────────────────────────────┤
    │  Foundations     │  Core styling utilities, helpers, enums  │
    │  Core            │  Theme system, MatTheme color presets    │
    │  Components      │  Buttons, Cards, Modals, Forms, Tables   │
    │  App Pages       │  Full-page layouts, navigation patterns  │
    │  Data Tables     │  DataTable, DataTableResource for CRUD   │
    │  Web Pages       │  Landing pages, marketing components     │
    ├─────────────────────────────────────────────────────────────┤
    │  BeerCSS         │  Material Design 3 CSS framework         │
    │  FastHTML        │  Python hypermedia web framework         │
    └─────────────────────────────────────────────────────────────┘

## 🎨 Available Themes

fh-matui includes 15+ pre-configured Material Design 3 color themes:

<table>
<thead>
<tr>
<th>Theme</th>
<th>Preview</th>
<th>Theme</th>
<th>Preview</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>MatTheme.red</code></td>
<td>🔴</td>
<td><code>MatTheme.pink</code></td>
<td>🩷</td>
</tr>
<tr>
<td><code>MatTheme.purple</code></td>
<td>🟣</td>
<td><code>MatTheme.deep_purple</code></td>
<td>💜</td>
</tr>
<tr>
<td><code>MatTheme.indigo</code></td>
<td>🔵</td>
<td><code>MatTheme.blue</code></td>
<td>💙</td>
</tr>
<tr>
<td><code>MatTheme.light_blue</code></td>
<td>🩵</td>
<td><code>MatTheme.cyan</code></td>
<td>🌊</td>
</tr>
<tr>
<td><code>MatTheme.teal</code></td>
<td>🩶</td>
<td><code>MatTheme.green</code></td>
<td>💚</td>
</tr>
<tr>
<td><code>MatTheme.light_green</code></td>
<td>🍀</td>
<td><code>MatTheme.lime</code></td>
<td>💛</td>
</tr>
<tr>
<td><code>MatTheme.yellow</code></td>
<td>🌟</td>
<td><code>MatTheme.amber</code></td>
<td>🧡</td>
</tr>
<tr>
<td><code>MatTheme.orange</code></td>
<td>🟠</td>
<td><code>MatTheme.deep_orange</code></td>
<td>🔶</td>
</tr>
<tr>
<td><code>MatTheme.brown</code></td>
<td>🟤</td>
<td><code>MatTheme.grey</code></td>
<td>⚪</td>
</tr>
<tr>
<td><code>MatTheme.blue_grey</code></td>
<td>🔘</td>
<td></td>
<td></td>
</tr>
</tbody>
</table>

**Usage:**

``` python
# Choose your theme
app, rt = fast_app(hdrs=[MatTheme.deep_purple.headers()])
```

## 🚀 Quick Start

Here’s a minimal example to get you started:

``` python
from fasthtml.common import *
from fh_matui.core import MatTheme
from fh_matui.components import Button, Card, FormField

# Create a themed FastHTML app
app, rt = fast_app(hdrs=[MatTheme.indigo.headers()])

@rt('/')
def home():
    return Div(
        Card(
            H3("Welcome to fh-matui!"),
            P("Build beautiful Material Design apps with Python."),
            Button("Get Started", cls="primary"),
        ),
        cls="padding"
    )

serve()
```

## 📦 Installation

``` bash
pip install fh-matui
```

### Dependencies

fh-matui automatically includes: - **python-fasthtml** - The core
FastHTML framework - **BeerCSS** - Loaded via CDN for Material Design 3
styling

### What This Code Does

1.  **`MatTheme.indigo.headers()`** - Loads BeerCSS with the indigo
    color scheme
2.  **[`Card`](https://abhisheksreesaila.github.io/fh-matui/components.html#card)** -
    Creates a Material Design card component with elevation
3.  **[`FormField`](https://abhisheksreesaila.github.io/fh-matui/components.html#formfield)** -
    Generates a styled input with floating label
4.  **`Button`** - Renders a Material Design button with ripple effects

## 📚 Module Reference

<table>
<colgroup>
<col style="width: 21%" />
<col style="width: 35%" />
<col style="width: 43%" />
</colgroup>
<thead>
<tr>
<th>Module</th>
<th>Description</th>
<th>Key Components</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="foundations.html">Foundations</a></td>
<td>Base utilities and helper functions</td>
<td><code>BeerHeaders</code>, <code>display</code>, styling helpers</td>
</tr>
<tr>
<td><a href="core.html">Core</a></td>
<td>Theme system and styling</td>
<td><code>MatTheme</code>, color presets, theme configuration</td>
</tr>
<tr>
<td><a href="components.html">Components</a></td>
<td>UI component library</td>
<td><code>Button</code>, <a
href="https://abhisheksreesaila.github.io/fh-matui/components.html#card"><code>Card</code></a>,
<a
href="https://abhisheksreesaila.github.io/fh-matui/components.html#formfield"><code>FormField</code></a>,
<a
href="https://abhisheksreesaila.github.io/fh-matui/components.html#formmodal"><code>FormModal</code></a>,
<a
href="https://abhisheksreesaila.github.io/fh-matui/components.html#grid"><code>Grid</code></a></td>
</tr>
<tr>
<td><a href="app_pages.html">App Pages</a></td>
<td>Application layouts</td>
<td>Navigation, sidebars, full-page layouts</td>
</tr>
<tr>
<td><a href="05_table.html">Data Tables</a></td>
<td>Data management components</td>
<td><a
href="https://abhisheksreesaila.github.io/fh-matui/datatable.html#datatable"><code>DataTable</code></a>,
<a
href="https://abhisheksreesaila.github.io/fh-matui/datatable.html#datatableresource"><code>DataTableResource</code></a>,
CRUD operations</td>
</tr>
<tr>
<td><a href="web_pages.html">Web Pages</a></td>
<td>Marketing/landing pages</td>
<td>Hero sections, feature grids, testimonials</td>
</tr>
</tbody>
</table>

## 🛠️ Development

### Install in Development Mode

``` bash
# Clone the repository
git clone https://github.com/user/fh-matui.git
cd fh-matui

# Install in editable mode
pip install -e .

# Make changes under nbs/ directory, then compile
nbdev_prepare
```

## 🤝 Why fh-matui?

<table>
<colgroup>
<col style="width: 36%" />
<col style="width: 63%" />
</colgroup>
<thead>
<tr>
<th>Challenge</th>
<th>fh-matui Solution</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>CSS complexity</strong></td>
<td>Pre-built Material Design 3 components via BeerCSS</td>
</tr>
<tr>
<td><strong>JavaScript fatigue</strong></td>
<td>FastHTML handles interactivity declaratively</td>
</tr>
<tr>
<td><strong>Component consistency</strong></td>
<td>Unified API across all components</td>
</tr>
<tr>
<td><strong>Dark mode support</strong></td>
<td>Built-in with automatic system preference detection</td>
</tr>
<tr>
<td><strong>Responsive design</strong></td>
<td>Mobile-first grid system and responsive utilities</td>
</tr>
<tr>
<td><strong>Form handling</strong></td>
<td><a
href="https://abhisheksreesaila.github.io/fh-matui/components.html#formfield"><code>FormField</code></a>,
<a
href="https://abhisheksreesaila.github.io/fh-matui/components.html#formgrid"><code>FormGrid</code></a>,
<a
href="https://abhisheksreesaila.github.io/fh-matui/components.html#formmodal"><code>FormModal</code></a>
for rapid form building</td>
</tr>
<tr>
<td><strong>Data management</strong></td>
<td><a
href="https://abhisheksreesaila.github.io/fh-matui/datatable.html#datatable"><code>DataTable</code></a>
and <a
href="https://abhisheksreesaila.github.io/fh-matui/datatable.html#datatableresource"><code>DataTableResource</code></a>
for CRUD operations</td>
</tr>
</tbody>
</table>

## 🤖 For LLM Users

fh-matui includes **comprehensive documentation bundles** for Large
Language Models, enabling AI assistants (like Claude, ChatGPT, or GitHub
Copilot) to help you build FastHTML apps with complete knowledge of the
component APIs.

### 📥 Download Context File

**[📄
llms-ctx.txt](https://raw.githubusercontent.com/abhisheksreesaila/fh-matui/main/llms-ctx.txt)**
— Complete API documentation in LLM-optimized format

### 💡 How to Use

1.  **Download the context file** from the link above
2.  **Attach it to your LLM conversation** (drag & drop or paste
    contents)
3.  **Ask for implementation** using natural language

**Example Prompt:**

    I'm using fh-matui (context attached). Create a dashboard with:
    - A sidebar navigation with 5 menu items
    - A DataTable showing products with pagination
    - A modal form to add/edit products
    - Use the deep purple theme

The LLM will generate production-ready FastHTML code using the exact
component APIs from the documentation.

### 🔄 Staying Up to Date

The `llms-ctx.txt` file is automatically regenerated with each release
to ensure it stays synchronized with the latest API changes. Always
download the version matching your installed package version for the
most accurate results.

> **📌 Note:** The context file is generated from the same literate
> programming notebooks that build the library itself, ensuring 100%
> accuracy with the actual implementation.

## 📄 License

This project is licensed under the Apache 2.0 License - see the
[LICENSE](https://github.com/user/fh-matui/blob/main/LICENSE) file for
details.

------------------------------------------------------------------------

**Built with ❤️ using FastHTML and nbdev**