126 lines
3.2 KiB
Markdown
126 lines
3.2 KiB
Markdown
# NiceGUI Extensions (niceguiex)
|
|
|
|
Extensions for NiceGUI including async elements with proper typing support and more. Create powerful UI components while maintaining full type hints and IDE support.
|
|
|
|
## Installation
|
|
|
|
Install directly from GitHub using uv or pip:
|
|
|
|
### Using uv
|
|
|
|
```bash
|
|
uv add git+https://github.com/yourusername/niceguiex.git
|
|
```
|
|
|
|
#### Using pip
|
|
|
|
```
|
|
pip install git+https://github.com/yourusername/niceguiex.git
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Example
|
|
|
|
```python
|
|
from nicegui import ui
|
|
from niceguiex.async_elements import AsyncElement, AsyncColumn, AsyncCard
|
|
|
|
# Create an async element that fetches data
|
|
class UserCard(AsyncElement[ui.column]):
|
|
async def build(self, user_id: int) -> None:
|
|
# Simulate async data fetching
|
|
user_data = await fetch_user(user_id)
|
|
|
|
with self:
|
|
with ui.card():
|
|
ui.label(user_data['name'])
|
|
ui.label(user_data['email'])
|
|
|
|
# Use in your NiceGUI app
|
|
@ui.page('/')
|
|
async def main():
|
|
# Creates the element and returns a properly typed ui.column
|
|
user_card = await UserCard.create(user_id=123)
|
|
user_card.classes('w-full') # Full IDE support!
|
|
```
|
|
|
|
### Using Inheritance
|
|
|
|
For even better typing, inherit from specific element types:
|
|
|
|
```python
|
|
class DataTable(AsyncColumn):
|
|
async def build(self, api_endpoint: str) -> None:
|
|
# Fetch data asynchronously
|
|
data = await fetch_data(api_endpoint)
|
|
|
|
with self:
|
|
ui.table(columns=data['columns'], rows=data['rows'])
|
|
|
|
# Usage
|
|
data_table = await DataTable.create(api_endpoint="/api/users")
|
|
# data_table is fully typed as DataTable/AsyncColumn
|
|
```
|
|
|
|
## Features
|
|
|
|
### Async Elements Module (`niceguiex.async_elements`)
|
|
- **Async Initialization**: Build UI elements that require async operations (API calls, database queries, etc.)
|
|
- **Full Type Support**: Maintains complete typing for IDE autocomplete and type checking
|
|
- **Context Manager Support**: Works seamlessly with NiceGUI's context manager pattern
|
|
- **Multiple Approaches**: Choose between generic `AsyncElement` or inherit from specific element types
|
|
- **Pre-built Async Components**: `AsyncColumn`, `AsyncRow`, `AsyncCard`, `AsyncDialog`, `AsyncTabs`, `AsyncScrollArea`, and more
|
|
|
|
### Additional Components
|
|
|
|
#### AutoScrollArea
|
|
Automatically scrolling area that follows content as it's added:
|
|
|
|
```python
|
|
from niceguiex.async_elements import AsyncScrollArea
|
|
|
|
class AutoScrollArea(AsyncScrollArea):
|
|
async def build(self) -> None:
|
|
# Automatically scrolls to bottom when content is added
|
|
pass
|
|
|
|
# Usage
|
|
auto_scroll = await AutoScrollArea.create()
|
|
with auto_scroll:
|
|
for message in messages:
|
|
ui.label(message)
|
|
```
|
|
|
|
#### ChatInput
|
|
Enhanced textarea for chat interfaces with Enter to send, Shift+Enter for new line:
|
|
|
|
```python
|
|
from chat_input import ChatInput
|
|
|
|
async def handle_message(message: str):
|
|
print(f"User sent: {message}")
|
|
|
|
chat = ChatInput(
|
|
placeholder='Type your message...',
|
|
on_enter=handle_message
|
|
).classes('w-full')
|
|
```
|
|
|
|
### Coming Soon
|
|
- Additional UI component extensions
|
|
- Helper utilities for common patterns
|
|
- Enhanced form handling
|
|
- And more!
|
|
|
|
## Development
|
|
|
|
Run the example:
|
|
|
|
```bash
|
|
python example.py
|
|
```
|
|
|
|
## License
|
|
|
|
MIT |