Metadata-Version: 2.5
Name: nicegui-bootstrap-components
Version: 0.1.2
Summary: Bootstrap 5 components for NiceGUI, matching the dash-bootstrap-components API, docs, and examples
Project-URL: Homepage, https://github.com/raffieeey/nicegui-bootstrap-components
Project-URL: Documentation, https://raffieeey.github.io/nicegui-bootstrap-components/
Author: raffieeey
License-Expression: MIT
License-File: LICENSE
Keywords: bootstrap,components,dashboard,nicegui,ui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Requires-Dist: nicegui<4,>=3.17.1
Provides-Extra: dbc-ref
Requires-Dist: dash-bootstrap-components==2.0.4; extra == 'dbc-ref'
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: pillow>=10; extra == 'dev'
Requires-Dist: playwright>=1.47; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: selenium>=4.20; extra == 'dev'
Provides-Extra: examples
Requires-Dist: pandas; extra == 'examples'
Description-Content-Type: text/markdown

# nicegui-bootstrap-components

Bootstrap 5 components for [NiceGUI](https://nicegui.io). The public API matches
the [dash-bootstrap-components](https://github.com/facultyai/dash-bootstrap-components)
2.0.4 API for the component set listed below.

[![CI](https://github.com/raffieeey/nicegui-bootstrap-components/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/raffieeey/nicegui-bootstrap-components/actions/workflows/ci.yml)
[![Python >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Install

The package requires Python 3.10 or later and NiceGUI >=3.17.1,<4; it has been
tested against NiceGUI 3.17.1. It bundles Bootstrap 5.3.8. CI checks the oldest
supported NiceGUI release and the newest available 3.x release.

```bash
pip install nicegui-bootstrap-components
```

`Table.from_dataframe` needs pandas, installed by the optional extra:

```bash
pip install "nicegui-bootstrap-components[examples]"
```

## Quickstart

Save this as `app.py` and run `python app.py`. Open the local URL printed in the
terminal.

```python
from nicegui import ui
from nicegui_bootstrap_components import bs

with bs.scope(), bs.container():
    with bs.row():
        with bs.col(width=12, md=6):
            bs.input(placeholder="Name")
            bs.button("Save", color="primary", on_click=lambda: ui.notify("Saved"))

ui.run()
```

## Two API surfaces

`nicegui_bootstrap_components.bs` is the native surface: 67 PascalCase classes
and 67 snake_case aliases (134 exports). Use it for new NiceGUI code.

`nicegui_bootstrap_components.dbc` is the compatibility surface (66 exports)
with dash-bootstrap-components 2.0.4 prop names. Use it when porting Dash layouts.

```python
from nicegui import ui
from nicegui_bootstrap_components import dbc

dbc.Container(
    dbc.Row(dbc.Col(dbc.Button("Save", color="primary"), md=6)),
    fluid=True,
)
```

Top-level exports: `StyleMode`, `ThemeController`, `bs`, `dbc`, `icons`, `setup`,
`themes`, `__version__`.

## Style modes

`setup()` registers library CSS once, process-wide, and is idempotent for the same
arguments. A conflicting mode, or scoped mode with `cdn=True`, raises `ValueError`.

- `StyleMode.UNSCOPED` (`"unscoped"`): Bootstrap-first page.
- `StyleMode.MIXED` (`"mixed"`): scoped Bootstrap islands inside an existing
  NiceGUI/Quasar page. Mark islands with `bs.scope()` (`bs.Scope` is the class form).

```python
from nicegui_bootstrap_components import StyleMode, setup, themes

setup(mode=StyleMode.MIXED, theme=themes.FLATLY, color_mode="auto")
```

## Themes and dark mode

27 constants on `themes`: Bootstrap itself, the grid-only build, and 25 Bootswatch
themes. `color_mode="auto"` follows the host app. Pass `icons.BOOTSTRAP` or
`icons.FONT_AWESOME` to `setup(icons=...)`.

`BOOTSTRAP`, `CERULEAN`, `COSMO`, `CYBORG`, `DARKLY`, `FLATLY`, `GRID`, `JOURNAL`,
`LITERA`, `LUMEN`, `LUX`, `MATERIA`, `MINTY`, `MORPH`, `PULSE`, `QUARTZ`, `SANDSTONE`,
`SIMPLEX`, `SKETCHY`, `SLATE`, `SOLAR`, `SPACELAB`, `SUPERHERO`, `UNITED`, `VAPOR`,
`YETI`, `ZEPHYR`.

## Components

67 native names (each has a snake_case alias on `bs`):

Accordion, AccordionItem, Alert, Badge, Breadcrumb, Button, ButtonGroup, Card, CardBody,
CardFooter, CardGroup, CardHeader, CardImg, CardImgOverlay, CardLink, Carousel, Checkbox,
Checklist, Col, Collapse, Container, DropdownMenu, DropdownMenuItem, Fade, Form,
FormFeedback, FormFloating, FormText, Input, InputGroup, InputGroupText, Label, ListGroup,
ListGroupItem, Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle, Nav, NavItem,
NavLink, Navbar, NavbarBrand, NavbarSimple, NavbarToggler, Offcanvas, Pagination,
Placeholder, Popover, PopoverBody, PopoverHeader, Progress, RadioButton, RadioItems, Row,
Scope, Select, Spinner, Stack, Switch, Tab, Table, Tabs, Textarea, Toast, Tooltip.

## Layout

```python
from nicegui_bootstrap_components import bs

with bs.scope(), bs.container():
    with bs.row():
        with bs.col(width=12, md=4):
            bs.label("Full width on phones, one third from md")
        with bs.col(width=12, md=4):
            bs.label("Middle")
        with bs.col(width=12, md=4):
            bs.label("Right")
```

## Forms

```python
from nicegui_bootstrap_components import bs

with bs.scope():
    bs.input(placeholder="Your name", on_change=lambda: None)
    bs.select(options={"my": "Malaysia", "sg": "Singapore"}, value="my")
    bs.checkbox(label="Remember me")
    bs.switch(label="Enable alerts")
```

## Cards, alerts, and badges

```python
from nicegui_bootstrap_components import bs

with bs.scope(), bs.card():
    bs.card_header("Header")
    with bs.card_body():
        bs.alert("Something happened.", color="info", dismissable=True)
        bs.badge("New", color="success")
```

## Modal

```python
from nicegui_bootstrap_components import bs

with bs.scope():
    with bs.modal() as modal:
        bs.modal_header("Title")
        bs.modal_body("Content")
        bs.modal_footer(bs.button("Close", on_click=modal.close))
```

## Table

```python
import pandas as pd
from nicegui_bootstrap_components import bs

df = pd.DataFrame({"city": ["Kuala Lumpur"], "country": ["Malaysia"]})

with bs.scope():
    bs.Table.from_dataframe(df, striped=True, bordered=False, hover=True)
```

## Examples

The gallery mirrors dash-bootstrap-components: Layer 1 component examples, Layer 2
composite apps (Iris, Graphs in Tabs, Simple Sidebar), and Layer 3 templates.

## Documentation

[https://raffieeey.github.io/nicegui-bootstrap-components/](https://raffieeey.github.io/nicegui-bootstrap-components/)

## Development

```bash
git clone https://github.com/raffieeey/nicegui-bootstrap-components.git
cd nicegui-bootstrap-components
pip install -e ".[dev]"
pytest
```

Install Chromium for browser tests with `python -m playwright install chromium`.
CI runs checks, documentation and browser jobs. The browser suite uses real
Chromium alongside a visual matrix. Python documentation blocks and examples
are executed by tests, so a snippet that cannot run fails CI.

## License

MIT. See [LICENSE](LICENSE).

## Status

0.1.2, security and correctness release. Matches the dash-bootstrap-components
2.0.4 API for the component set listed above, with documented adaptations.
Built-in persistence is unsupported: non-off persistence modes raise an error.
Use application-managed storage instead.
