# StarUI
**Python-first UI component library for StarHTML applications**
Modern, type-safe components with shadcn/ui styling and zero-configuration setup.
[](https://badge.fury.io/py/starui)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/microsoft/pyright)
## ✨ Features
- 🎨 **shadcn/ui components** - Pixel-perfect implementations with modern design
- ⚡ **Zero configuration** - Works out of the box with sensible defaults
- 🚯 **StarHTML native** - Built specifically for StarHTML applications
- 📱 **Responsive design** - Mobile-first with Tailwind CSS v4
- 🔒 **Type-safe APIs** - Excellent developer experience with pragmatic typing
- 🚀 **Modern Python** - Python 3.12+ with latest language features
## 🚀 Quick Start
### Installation
```bash
# With pip
pip install starui
# With uv (recommended)
uv add starui
```
### Create Your First Project
```bash
# Initialize a new StarUI project
star init my-app
cd my-app
# Add some components
star add button
star add card
# Run development server
star dev app.py
```
### Basic Usage
```python
from starhtml import *
from starui import * # Gets all components automatically
# Create a StarHTML app
app, rt = star_app()
@rt("/")
def home():
return Card(
CardHeader(
CardTitle("Welcome to StarUI")
),
CardContent(
Button("Get Started", variant="default"),
Button("Learn More", variant="outline")
)
)
if __name__ == "__main__":
serve()
```
## 📦 Available Components
| Component | Description | Variants |
|-----------|-------------|----------|
| **Button** | Interactive buttons | `default`, `destructive`, `outline`, `secondary`, `ghost`, `link` |
| **Alert** | Important messages | `default`, `destructive` |
| **Badge** | Status indicators | `default`, `secondary`, `destructive`, `outline` |
| **Card** | Content containers | Header, Content, Footer sections |
| **Input** | Form inputs | All HTML input types with validation |
| **Label** | Form labels | Accessible form labeling |
## 🛠 CLI Commands
```bash
# Project initialization
star init <project-name> # Create new StarUI project
# Component management
star add <component> # Add component to project
star list # List available components
# Development
star dev <app.py> # Development server with hot reload
star build # Build production CSS
```
## 🎯 Component API
### Button Example
```python
from starui import Button # Or: from starui import *
# Basic usage
Button("Click me")
# With variants and props
Button(
"Submit Form",
variant="default",
size="lg",
disabled=False,
type="submit",
onclick="handleSubmit()"
)
```
### Card Example
```python
from starui import * # Gets Card, CardHeader, CardTitle, CardContent, Button, etc.
Card(
CardHeader(
CardTitle("Product Card")
),
CardContent(
P("This is the card content with detailed information."),
Button("Learn More", variant="outline")
),
class_name="max-w-md"
)
```
## ⚙️ Configuration
StarUI works with zero configuration, but you can customize it:
```python
# starui.config.py (optional)
from starui.config import ProjectConfig
from pathlib import Path
config = ProjectConfig(
project_root=Path.cwd(),
css_output=Path("static/css/starui.css"),
component_dir=Path("components/ui")
)
```
## 🔗 StarHTML Integration
StarUI is built specifically for [StarHTML](https://github.com/banditburai/starhtml):
```python
from starhtml import *
from starui import Button, Alert
app, rt = star_app(
hdrs=(
Link(rel="stylesheet", href="/static/css/starui.css"),
)
)
@rt("/")
def home():
return Div(
Alert(
"Welcome to your new StarUI app!",
variant="default"
),
Button("Get Started", variant="default"),
cls="p-8 max-w-md mx-auto"
)
```
## 💻 Development
### Setup
```bash
# Clone the repository
git clone https://github.com/banditburai/starui.git
cd starui
# Install with uv (recommended)
uv sync --all-extras
# Or with pip
pip install -e ".[dev]"
```
### Quality Checks
```bash
# Run all quality checks
uv run ruff check # Linting
uv run ruff format --check # Formatting
uv run pyright # Type checking
uv run pytest tests/ -v # Testing
```
### Building
```bash
uv build # Build package
uv run star --version # Test CLI
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-component`)
3. Make your changes with tests
4. Run quality checks (`uv run ruff check && uv run pyright && uv run pytest`)
5. Submit a Pull Request
## 🙏 Acknowledgments
- [shadcn/ui](https://ui.shadcn.com/) - Design system and component inspiration
- [StarHTML](https://github.com/banditburai/starhtml) - The amazing Python web framework
- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
- [FastHTML](https://fastht.ml/) - Inspiration for Python-first web development
---
**Made with ❤️ for the Python web development community**
Raw data
{
"_id": null,
"home_page": null,
"name": "starui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ui, components, tailwind, datastar, starhtml, fasthtml",
"author": "firefly",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6b/53/a0edbe1c9b72ab20047543889402469011567062bafa85e45a78618e0c3a/starui-0.1.4.tar.gz",
"platform": null,
"description": "# StarUI\n\n**Python-first UI component library for StarHTML applications**\n\nModern, type-safe components with shadcn/ui styling and zero-configuration setup.\n\n[](https://badge.fury.io/py/starui)\n[](https://www.python.org/downloads/)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/microsoft/pyright)\n\n## \u2728 Features\n\n- \ud83c\udfa8 **shadcn/ui components** - Pixel-perfect implementations with modern design\n- \u26a1 **Zero configuration** - Works out of the box with sensible defaults \n- \ud83d\udeaf **StarHTML native** - Built specifically for StarHTML applications\n- \ud83d\udcf1 **Responsive design** - Mobile-first with Tailwind CSS v4\n- \ud83d\udd12 **Type-safe APIs** - Excellent developer experience with pragmatic typing\n- \ud83d\ude80 **Modern Python** - Python 3.12+ with latest language features\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# With pip\npip install starui\n\n# With uv (recommended)\nuv add starui\n```\n\n### Create Your First Project\n\n```bash\n# Initialize a new StarUI project\nstar init my-app\ncd my-app\n\n# Add some components \nstar add button\nstar add card\n\n# Run development server\nstar dev app.py\n```\n\n### Basic Usage\n\n```python\nfrom starhtml import *\nfrom starui import * # Gets all components automatically\n\n# Create a StarHTML app\napp, rt = star_app()\n\n@rt(\"/\")\ndef home():\n return Card(\n CardHeader(\n CardTitle(\"Welcome to StarUI\")\n ),\n CardContent(\n Button(\"Get Started\", variant=\"default\"),\n Button(\"Learn More\", variant=\"outline\")\n )\n )\n\nif __name__ == \"__main__\":\n serve()\n```\n\n## \ud83d\udce6 Available Components\n\n| Component | Description | Variants |\n|-----------|-------------|----------|\n| **Button** | Interactive buttons | `default`, `destructive`, `outline`, `secondary`, `ghost`, `link` |\n| **Alert** | Important messages | `default`, `destructive` |\n| **Badge** | Status indicators | `default`, `secondary`, `destructive`, `outline` |\n| **Card** | Content containers | Header, Content, Footer sections |\n| **Input** | Form inputs | All HTML input types with validation |\n| **Label** | Form labels | Accessible form labeling |\n\n## \ud83d\udee0 CLI Commands\n\n```bash\n# Project initialization\nstar init <project-name> # Create new StarUI project\n\n# Component management \nstar add <component> # Add component to project\nstar list # List available components\n\n# Development\nstar dev <app.py> # Development server with hot reload\nstar build # Build production CSS\n```\n\n## \ud83c\udfaf Component API\n\n### Button Example\n\n```python\nfrom starui import Button # Or: from starui import *\n\n# Basic usage\nButton(\"Click me\")\n\n# With variants and props\nButton(\n \"Submit Form\",\n variant=\"default\",\n size=\"lg\", \n disabled=False,\n type=\"submit\",\n onclick=\"handleSubmit()\"\n)\n```\n\n### Card Example\n\n```python\nfrom starui import * # Gets Card, CardHeader, CardTitle, CardContent, Button, etc.\n\nCard(\n CardHeader(\n CardTitle(\"Product Card\")\n ),\n CardContent(\n P(\"This is the card content with detailed information.\"),\n Button(\"Learn More\", variant=\"outline\")\n ),\n class_name=\"max-w-md\"\n)\n```\n\n## \u2699\ufe0f Configuration\n\nStarUI works with zero configuration, but you can customize it:\n\n```python\n# starui.config.py (optional)\nfrom starui.config import ProjectConfig\nfrom pathlib import Path\n\nconfig = ProjectConfig(\n project_root=Path.cwd(),\n css_output=Path(\"static/css/starui.css\"),\n component_dir=Path(\"components/ui\")\n)\n```\n\n## \ud83d\udd17 StarHTML Integration\n\nStarUI is built specifically for [StarHTML](https://github.com/banditburai/starhtml):\n\n```python\nfrom starhtml import *\nfrom starui import Button, Alert\n\napp, rt = star_app(\n hdrs=(\n Link(rel=\"stylesheet\", href=\"/static/css/starui.css\"),\n )\n)\n\n@rt(\"/\")\ndef home():\n return Div(\n Alert(\n \"Welcome to your new StarUI app!\",\n variant=\"default\"\n ),\n Button(\"Get Started\", variant=\"default\"),\n cls=\"p-8 max-w-md mx-auto\"\n )\n```\n\n## \ud83d\udcbb Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/banditburai/starui.git\ncd starui\n\n# Install with uv (recommended)\nuv sync --all-extras\n\n# Or with pip \npip install -e \".[dev]\"\n```\n\n### Quality Checks\n\n```bash\n# Run all quality checks\nuv run ruff check # Linting\nuv run ruff format --check # Formatting \nuv run pyright # Type checking\nuv run pytest tests/ -v # Testing\n```\n\n### Building\n\n```bash\nuv build # Build package\nuv run star --version # Test CLI\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-component`) \n3. Make your changes with tests\n4. Run quality checks (`uv run ruff check && uv run pyright && uv run pytest`)\n5. Submit a Pull Request\n\n## \ud83d\ude4f Acknowledgments\n\n- [shadcn/ui](https://ui.shadcn.com/) - Design system and component inspiration\n- [StarHTML](https://github.com/banditburai/starhtml) - The amazing Python web framework\n- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework\n- [FastHTML](https://fastht.ml/) - Inspiration for Python-first web development\n\n---\n\n**Made with \u2764\ufe0f for the Python web development community**",
"bugtrack_url": null,
"license": null,
"summary": "Python-first UI component library for Datastar/StarHTML applications",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [
"ui",
" components",
" tailwind",
" datastar",
" starhtml",
" fasthtml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c97dc495e6f40fb796b5bf18ac46d0a748599738bf5e90191064f63db8840672",
"md5": "87c34d71e6c6d8a93c2ef74cf37a4ada",
"sha256": "49866290a36934b6ff20360fcc27badcba1971cd605f4ab439a7d8ee031fa802"
},
"downloads": -1,
"filename": "starui-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87c34d71e6c6d8a93c2ef74cf37a4ada",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 35323,
"upload_time": "2025-08-19T16:18:04",
"upload_time_iso_8601": "2025-08-19T16:18:04.445975Z",
"url": "https://files.pythonhosted.org/packages/c9/7d/c495e6f40fb796b5bf18ac46d0a748599738bf5e90191064f63db8840672/starui-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6b53a0edbe1c9b72ab20047543889402469011567062bafa85e45a78618e0c3a",
"md5": "3025adae43a97fbb2e81b213cb249b42",
"sha256": "0ae6d375278bf1679cec85151848da9d14f20cf3349a9cdcd6bdce9a064d1f7a"
},
"downloads": -1,
"filename": "starui-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "3025adae43a97fbb2e81b213cb249b42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 24855,
"upload_time": "2025-08-19T16:18:05",
"upload_time_iso_8601": "2025-08-19T16:18:05.524869Z",
"url": "https://files.pythonhosted.org/packages/6b/53/a0edbe1c9b72ab20047543889402469011567062bafa85e45a78618e0c3a/starui-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 16:18:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "starui"
}
JSON