streamlit-listview 1.0.0__tar.gz

streamlit_listview-1.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Leland Grunt
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

streamlit_listview-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include streamlit_listview/frontend/build *
+include pyproject.toml
+include _build_backend.py

streamlit_listview-1.0.0/NOTICE

@@ -0,0 +1,64 @@
+Streamlit Listview
+Copyright 2026 Leland Grunt
+
+This product includes software developed by third parties, attributed below.
+
+===============================================================================
+Streamlit — Apache License, Version 2.0
+===============================================================================
+
+The remark/rehype Markdown directive plugins in
+streamlit_listview/frontend/src/markdown/streamlitPlugins.ts — colored text
+(:color[…]), colored background (:color-background[…]), badges
+(:color-badge[…]), small text (:small[…]), shimmer (:shimmer[…]),
+Material icons (:material/icon:), the :streamlit: logo, typographical-symbol
+replacement, the LABEL_DISALLOWED_ELEMENTS blocklist, and escapeLabelSource —
+are ported from Streamlit's StreamlitMarkdown component.
+
+Source: frontend/lib/src/components/shared/StreamlitMarkdown/StreamlitMarkdown.tsx
+        (and its co-located utils.ts / styled-components.ts)
+Project: https://github.com/streamlit/streamlit
+
+Copyright (c) Snowflake Inc. and the Streamlit authors.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use these files except in compliance with the License. You may obtain a copy
+of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations under
+the License.
+
+===============================================================================
+react-feather — MIT License
+===============================================================================
+
+The HelpCircle icon SVG path data reproduced inline in
+streamlit_listview/frontend/src/components/HelpTooltip.tsx is the "help-circle" glyph
+from react-feather (a React port of the Feather icon set).
+
+Project: https://github.com/feathericons/react-feather
+
+Copyright (c) 2017 Cole Bemis (Feather icons) and the react-feather authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streamlit_listview-1.0.0/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: streamlit-listview
+Version: 1.0.0
+Summary: Streamlit Components V2 selectable list widget with search, groups, and theming
+Author-email: Leland Grunt <33732585+LelandGrunt@users.noreply.github.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/LelandGrunt/streamlit-listview
+Project-URL: Repository, https://github.com/LelandGrunt/streamlit-listview
+Project-URL: Issues, https://github.com/LelandGrunt/streamlit-listview/issues
+Project-URL: Release Notes, https://github.com/LelandGrunt/streamlit-listview/releases
+Keywords: streamlit,streamlit-component,components-v2,listview,list,widget,selection,ui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: streamlit>=1.51
+Provides-Extra: devel
+Requires-Dist: wheel; extra == "devel"
+Requires-Dist: pytest; extra == "devel"
+Requires-Dist: pytest-cov; extra == "devel"
+Requires-Dist: playwright; extra == "devel"
+Requires-Dist: pytest-playwright; extra == "devel"
+Requires-Dist: requests; extra == "devel"
+Requires-Dist: pytest-rerunfailures; extra == "devel"
+Dynamic: license-file
+
+[![Open in Streamlit](https://img.shields.io/badge/Open_in_Streamlit-FF4B4B?logo=streamlit&logoColor=white)](https://st-listview-demo.streamlit.app/)
+[![PyPI](https://img.shields.io/pypi/v/streamlit-listview?logo=pypi&logoColor=white&color=3775A9)](https://pypi.org/project/streamlit-listview/)
+![Python](https://img.shields.io/badge/python-%E2%89%A5_3.10-3776AB?logo=python&logoColor=white)
+![Streamlit](https://img.shields.io/badge/Streamlit-%E2%89%A5_1.51-FF4B4B?logo=streamlit&logoColor=white)
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+[![License](https://img.shields.io/badge/license-Apache_2.0-green)](https://github.com/LelandGrunt/streamlit-listview/blob/HEAD/LICENSE)
+
+# Streamlit Listview
+
+A selectable, scrollable **list widget** for Streamlit — with grouping, search, sorting, multi-select, and native theming. It renders **inline** in the page (no iframe) and inherits your Streamlit theme automatically.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LelandGrunt/streamlit-listview/HEAD/assets/listview-demo.gif" alt="streamlit-listview: live search, grouping, multi-select, and a select-all toggle" width="480">
+</p>
+
+<p align="center"><sub>Live search · collapsible groups · multi-select · select-all — all themed by Streamlit, no iframe.</sub></p>
+
+## Why listview?
+
+`st.multiselect` and `st.radio` are great for a handful of options, but they don't scroll, group, or search well once the list grows. `listview` is a dedicated, always-visible list surface:
+
+- **Single / multi selection** with an optional `max_selections` cap.
+- **Grouping** with sticky headers and optional **collapsible groups**.
+- **Live search** — filters by label as you type, optionally **pinned** (stays put while the list scrolls).
+- **Sorting** — order items, group headers, or both alphabetically (ascending or descending).
+- **Select all / Deselect all** toggle for multi-select, scoped to the rows matching the current search — including rows inside collapsed groups (collapse is visual, not a filter) — excluding disabled rows.
+- **Add new options** — let users enter values that aren't in the list (returned as the typed string). Typing the visible text of an option that is already there selects that option instead of adding a duplicate row.
+- **Jump to default** — auto-scrolls the default selection into view on first render, and again whenever `default` changes (the list scrolls, never the surrounding page).
+- **Native theming** — pure `--st-*` CSS variables, so light, dark, and custom themes apply automatically. No Bootstrap, no hardcoded palette.
+- **Markdown labels & help** — Streamlit-parity Markdown (GFM + Streamlit directives like `:red[…]`, badges, `:material/icon:`, `:streamlit:`, emoji).
+- **Keyboard & screen-reader friendly** — `role="listbox"`/`option`, named `role="group"` per group header, the listbox named after your `label` (also when it is hidden or collapsed), arrow-key navigation, `/` to jump to the search field, and `aria-*` state.
+- **Returns what you passed in** — select a dict, get that dict back (metadata and all).
+
+Built on [**Streamlit Components V2**](https://docs.streamlit.io/develop/concepts/custom-components/components-v2): the widget renders inline in the host page (inside a Shadow DOM), not in an iframe.
+
+## Installation
+
+```sh
+uv pip install streamlit-listview
+```
+
+Requires **Python ≥ 3.10** and **Streamlit ≥ 1.51**.
+
+## Quickstart
+
+```python
+import streamlit as st
+from streamlit_listview import listview
+
+choice = listview(
+    "Pick a fruit",
+    ["Apple", "Banana", "Cherry"],
+    selection_mode="single",
+    key="fruit",
+)
+st.write("You picked:", choice)
+```
+
+Grouped, multi-select, searchable, with a help tooltip:
+
+```python
+choice = listview(
+    "Pick ingredients",
+    [
+        {"id": "apple", "label": "Apple", "group": "Fruit"},
+        {"id": "carrot", "label": "Carrot", "group": "Vegetable"},
+        {"id": "salmon", "label": "Salmon", "group": "Fish", "disabled": True},
+    ],
+    selection_mode="multi",
+    max_selections=2,
+    enable_search=True,
+    pin_search=True,
+    collapsible_groups=True,
+    select_all=True,
+    help="Pick up to **two** ingredients.",
+    key="ingredients",
+)
+st.write(choice)
+```
+
+## API
+
+<details>
+<summary><strong>Full signature</strong></summary>
+
+```python
+def listview(
+    label,
+    options=None,
+    *,
+    selection_mode="single",          # "single" | "multi"
+    default=None,                     # option id, or list of ids (multi)
+    format_func=None,                 # maps an option -> display label
+    enable_search=False,
+    pin_search=False,                 # sticky search field; requires enable_search=True
+    search_placeholder="Search",
+    collapsible_groups=False,
+    collapsed_groups=None,            # ["GroupA", ...] | "all" | None — initial state, per group
+    sort=None,                        # "items" | "groups" | "both" | None
+    sort_ascending=True,              # True = A→Z; False = Z→A; only when sort is set
+    accept_new_options=False,
+    max_selections=None,              # multi mode; single accepts None or 1
+    select_all=False,                 # multi mode only; adds a Select all / Deselect all toggle
+    placeholder=None,                 # text shown when options is empty
+    height=300,                       # px, >= 100
+    item_height=None,                 # px, >= 1; minimum row height (floor), None = auto
+    content_font_size=None,           # px, >= 1; font size of rows + group headers, None = theme default
+    width="stretch",                  # "stretch" | int (px, >= 1)
+    show_grid_lines=True,             # divider lines between rows; False for a compact list
+    help=None,                        # Markdown tooltip; shown when label is visible
+    disabled=False,
+    label_visibility="visible",       # "visible" | "hidden" | "collapsed"
+    on_change=None,
+    args=None,
+    kwargs=None,
+    key=None,                         # strongly recommended (see Keying)
+) -> dict | str | int | list | None: ...
+```
+
+</details>
+
+### Parameters
+
+| Parameter            | Description                                                                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`              | Text above the list; renders inline Markdown (see [Markdown](#markdown-label--help)).                                                |
+| `options`            | The options — simple `str`/`int` values or dicts (see [Options](#options)).                                                          |
+| `selection_mode`     | `"single"` (the default) or `"multi"`.                                                                                               |
+| `default`            | Initially selected option id (or list of ids in multi mode); applied at mount only (see [Keying](#keying)).                          |
+| `format_func`        | Maps an **option** — the dict, or the scalar itself — to its display label; an explicit dict `label` wins (see [Options](#options)). |
+| `enable_search`      | Adds a search field that live-filters the list by label.                                                                             |
+| `pin_search`         | Keeps the search field in view while the list scrolls; requires `enable_search=True`.                                                |
+| `search_placeholder` | Placeholder text of the search field.                                                                                                |
+| `collapsible_groups` | Makes every group header a collapse/expand toggle.                                                                                   |
+| `collapsed_groups`   | Groups that start collapsed: `["GroupA", ...]` or `"all"` (see [Collapsible groups](#collapsible-groups)).                           |
+| `sort`               | Alphabetical ordering: `"items"`, `"groups"`, `"both"`, or `None` for input order (see [Sorting](#sorting)).                         |
+| `sort_ascending`     | `True` = A→Z (the default), `False` = Z→A; only meaningful when `sort` is set.                                                       |
+| `accept_new_options` | Lets users add values not in the list; returned as the typed string.                                                                 |
+| `max_selections`     | Cap on the multi-mode selection (single mode accepts `None` or `1`).                                                                 |
+| `select_all`         | Multi mode only: adds the Select all / Deselect all toggle.                                                                          |
+| `placeholder`        | Text shown instead of the list when `options` is empty.                                                                              |
+| `height`             | List height in px (≥ 100).                                                                                                           |
+| `item_height`        | Minimum row height in px — a floor, rows still grow to fit their content; `None` = auto.                                             |
+| `content_font_size`  | Font size in px of rows and group headers; `None` = theme default.                                                                   |
+| `width`              | `"stretch"` (fill the container, the default) or a pixel width (≥ 1).                                                                |
+| `show_grid_lines`    | Divider lines between rows; `False` for a compact, line-free list.                                                                   |
+| `help`               | Markdown tooltip beside the label; shown only while the label is visible.                                                            |
+| `disabled`           | Disables the whole widget.                                                                                                           |
+| `label_visibility`   | `"visible"`, `"hidden"` (keeps the label's space), or `"collapsed"`.                                                                 |
+| `on_change`          | Callback invoked when the selection changes, called as `on_change(*args, **kwargs)`.                                                 |
+| `args`               | Positional arguments for `on_change`.                                                                                                |
+| `kwargs`             | Keyword arguments for `on_change`.                                                                                                   |
+| `key`                | Widget identity across reruns — strongly recommended (see [Keying](#keying)).                                                        |
+
+### Options
+
+- **Simple values** (`str | int`): the value is both the id and the label, e.g. `["Apple", "Banana"]`.
+- **Dicts**: `{"id": ..., "label": ..., "group": ..., "disabled": ...}`
+  - `id` (**required**; `str` or `int` — nothing else, not even `bool` or `float`)
+  - `label` (optional display text; when missing, `None`, or NaN — the last two are what `df.to_dict("records")` yields for a NULL cell — the label comes from `format_func(option)`, i.e. `str(id)` when `format_func` is `None`, the default)
+  - `group` (optional `str`; items sharing a `group` render under one header)
+  - `disabled` (optional `bool`; visible but not selectable)
+  - any **extra fields** (e.g. a `payload`) are never rendered directly, and come back untouched in the selection result — handy for attaching your own metadata to an option. `format_func` *can* read them to build the displayed label (see below).
+
+Ids are validated at the boundary, because the frontend identifies each row by JavaScript `String(id)`: they must be **unique as rendered** (`1` and `"1"` collide, and so would a `bool`), and an `int` id must fit JavaScript's safe-integer range (`abs(id) <= 2**53 - 1`) since the payload travels as JSON and larger ints lose precision as doubles — use the string form for BIGINT or snowflake keys.
+
+`default` ids are validated exactly like option ids: `str` or `int` only (`bool` is rejected), an `int` must satisfy `abs(id) <= 2**53 - 1`, and — unless `accept_new_options=True` — each must name an option by its rendered `String(id)` identity.
+
+`format_func` runs server-side, receives the **option as passed** — the dict for dict options, the scalar itself for simple values — and returns its display label. An explicit `label` always wins, so you can format some rows and hand-write the rest. Because the whole option arrives, the label can be built from fields the widget never renders:
+
+```python
+listview(
+    "Objects",
+    options=[
+        {"id": 1, "text": "Orders",     "type": "Table"},
+        {"id": 2, "text": "OrdersView", "type": "View"},
+    ],
+    format_func=lambda o: f"{o['text']}{'' if o['type'] == 'Table' else ' 👓'}",
+)
+# rows read "Orders" and "OrdersView 👓"
+```
+
+Two things to know about which options reach it:
+
+- `{"label": None}` and `{"label": nan}` *carry* a `label` key and still go through `format_func`, because neither is usable display text — and that is exactly what `df.to_dict("records")` produces for a NULL cell. So "all my dicts have a `label`" is not a safe assumption; write the formatter to cope, or it will raise a `ValueError` naming the option.
+- Scalar options arrive as themselves, so one formatter has to handle both shapes if your data mixes them: `option["id"] if isinstance(option, dict) else option`.
+
+`format_func=None` (the default) means *no* formatter: the label is `str(id)`. Don't pass `str` to get that — `str` would receive the option and render a dict repr. The option you get is your own object, not a copy; treat it as read-only.
+
+### Sorting
+
+By default options render in the order you pass them (`sort=None`). Set `sort` to reorder alphabetically by the displayed label / group name (case-insensitive, stable):
+
+- `sort="items"` — sort options within each group; group order unchanged.
+- `sort="groups"` — sort the group headers; option order within a group unchanged.
+- `sort="both"` — sort both.
+
+`sort_ascending=False` reverses the order. When groups are sorted, **ungrouped options always render last**. Entries added via `accept_new_options` are appended at the bottom — below every group — and are not sorted.
+
+### Collapsible groups
+
+With `collapsible_groups=True` every group header becomes a toggle. `collapsed_groups` (`["GroupA", ...]` or `"all"`) is **initial state, applied per group the first time that group appears while `collapsible_groups=True`** — at mount for the groups your options already contain, and on the later rerun that first brings a group in for the rest (options fetched asynchronously, or loaded behind a button, reach the widget after mount). Once a group has been seen the user owns it: a manual toggle is never overridden, and neither is a `collapsed_groups` change on a keyed instance — change the `key` to re-apply it (see [Keying](#keying)). Groups only ever shown with `collapsible_groups=False` do not count as seen, so enabling `collapsible_groups` later on a keyed instance applies `collapsed_groups` to them at that point.
+
+The sharp edge of "per group": with `collapsed_groups="all"`, a **brand-new group that appears after mount starts collapsed**. If you append a group to a live list and want it open, name the groups explicitly instead of using `"all"`. A group that disappears and later comes back still counts as seen, so it returns **open** rather than collapsed a second time.
+
+### Return value
+
+You get back what you passed in:
+
+- **single** → the selected option exactly as passed (dict or scalar), or `None`.
+- **multi** → a list of the selected options, in selection order; `[]` if none.
+- Entries added via `accept_new_options` come back as the **plain string** the user typed.
+
+### Changing `options`, `max_selections` or `selection_mode` later
+
+On a **keyed** widget the selection survives a rerun (an unkeyed one remounts and resets), so it can outlive the data it was made against. When that happens the widget re-derives the selection from the current data and **commits the correction**, so the rows you see and the value `listview()` returns cannot disagree. In selection order, it drops:
+
+- ids that are no longer in `options` (kept as typed strings when `accept_new_options=True`);
+- everything past a freshly lowered `max_selections` — the earliest-selected survive;
+- everything past the first entry when `selection_mode` flips from `"multi"` to `"single"`.
+
+A selected option that merely became `disabled` is **not** dropped — a disabled selection is locked, not removed.
+
+Two consequences to plan for:
+
+- **`on_change` fires once** on that rerun. A correction is written back through the same channel a click uses, and Components V2 offers no second one for it, so the callback cannot tell them apart. If yours must run for real user input only, compare against the previous selection yourself.
+- **The returned value never shows the uncorrected selection.** The write-back is what triggers the rerun that carries the correction, so it arrives one rerun late — but `listview()` applies the same rules on the way out (ids are matched to options by their rendered `String(id)` identity, ids matching no option are dropped, duplicate spellings of one row collapse, and the multi list is truncated to `max_selections`, keeping the same earliest-selected survivors), so it cannot hand back more options than you allow, an option you removed, or one row twice. Nothing lags: a typed `"7"` after you promote the int `7` into `options` comes back as that option immediately.
+
+### Markdown (label & help)
+
+`label` and `help` render as Markdown using the same engine Streamlit's own widgets use:
+
+- **`label`** — restricted **inline** tier: bold, italics, strikethrough, inline `code`, links, inline images, plus Streamlit extras (`:red[…]` and other colors, `:color-background[…]`, `:color-badge[…]`, `:small[…]`, `:material/icon:`, `:streamlit:`, emoji shortcodes). Block elements are suppressed.
+- **`help`** — full **GitHub-Flavored Markdown** (headings, lists, tables, blockquotes, fenced code, …) plus the same extras. Shown only when `label_visibility="visible"`.
+
+> **Note:** LaTeX/KaTeX is intentionally not supported (`$…$` renders as literal text), and there is no `unsafe_allow_html` — raw HTML stays escaped.
+
+### Theming
+
+All styling uses Streamlit's `--st-*` CSS custom properties (e.g. `--st-primary-color`, `--st-background-color`, `--st-text-color`, `--st-font`, radius variables), so light, dark, and custom themes apply automatically. The label, help icon, and tooltip replicate Streamlit's built-in widget look.
+
+The list itself looks like an open `st.selectbox` menu, and each state borrows the native widget that plays the same part:
+
+- **Hover** — the menu's grey highlight pill, computed with the same formula Streamlit's theme uses, so it follows custom themes too.
+- **Selected rows** — an active `st.pills`: the primary color at 10 % with primary-colored text.
+- **Group headers** — the `st.dataframe` header band.
+- **Search field** — filled like `st.text_input`.
+- **Frame** — turns the primary color only while the widget has focus, like every native input; hovering or scrolling leaves it alone. A click anywhere inside the frame, including the empty space below a short list, focuses the list.
+
+In `st.sidebar` the widget detects its container and adapts. Streamlit's sidebar theme swaps `--st-background-color` with `--st-secondary-background-color`; the list undoes that swap and stays on the menu's surface, which is what `st.selectbox` opens onto in either container (white in the light theme, `#0e1117` in the dark one). The search field swaps with it, so it still stands out from the list. Nothing to configure, and a custom `[theme.sidebar]` is respected — the colors are derived from the tokens, never hardcoded.
+
+The hover highlight uses CSS relative color syntax (Chrome/Edge 119+, Firefox 128+, Safari 18+). Older browsers show a close approximation instead.
+
+### Keying
+
+`key` is **strongly recommended for any dynamic app.** With a `key`, Streamlit updates the existing element in place when other parameters change, so frontend-local UI state (collapse, search text, focus, scroll) **and** the selection survive. Without a `key`, *any* parameter change remounts the widget and resets that state — so changing the `key` is the deliberate way to reset the widget.
+
+A keyed widget's selection also survives moving it between containers (say `st.sidebar` ↔ the main body): the move rebuilds the frontend, but the widget re-seeds its rows from the selection persisted in `st.session_state`, so the rows and the returned value both carry over — only frontend-local UI state (search text, scroll, collapse) resets.
+
+Because the selection survives, two parameters only take effect at mount: changing `default` on a keyed widget moves neither the displayed selection nor the returned value — it only scrolls the newly named row into view — and changing `collapsed_groups` never re-collapses a group that has already been shown ([Collapsible groups](#collapsible-groups)). Change the `key` to re-apply either. A keyed selection that no longer fits the current parameters is corrected instead — see [Changing `options`, `max_selections` or `selection_mode` later](#changing-options-max_selections-or-selection_mode-later).
+
+## Demo
+
+An interactive playground — every parameter as a live control, plus a generated code snippet and an API reference — lives in [`demo/`](https://github.com/LelandGrunt/streamlit-listview/tree/HEAD/demo):
+
+```sh
+uv run streamlit run demo/app.py
+```
+
+The demo needs the package **installed** — `uv run` does that for you, including the compiled frontend in `streamlit_listview/frontend/build/` (a generated, git-ignored artifact). A separate `npm run build` is only needed after editing `streamlit_listview/frontend/src/` (see [Building from source](#building-from-source)). See [`demo/README.md`](https://github.com/LelandGrunt/streamlit-listview/blob/HEAD/demo/README.md) for details.
+
+## Building from source
+
+### Development install (editable)
+
+From the directory containing the root `pyproject.toml`:
+
+```sh
+uv venv                                # once, if there is no .venv yet
+uv pip install -e . --force-reinstall
+```
+
+On a clean clone this also triggers the frontend build via the build backend
+(Node.js ≥ 24 required). Set `LISTVIEW_SKIP_NPM_BUILD=1` to skip it when the
+bundle is already built — e.g. after a manual `npm run build` in
+`streamlit_listview/frontend/`.
+
+### Build a wheel
+
+```sh
+uv build
+```
+
+The build backend compiles the frontend automatically (`npm ci` if needed, then
+`npm run build`) before packaging, so the wheel always bundles a fresh
+`streamlit_listview/frontend/build` **and** the nested
+`streamlit_listview/pyproject.toml` component manifest (Streamlit reads it at
+runtime to resolve the asset globs). This produces `dist/`:
+
+- `dist/streamlit_listview-1.0.0-py3-none-any.whl`
+- `dist/streamlit_listview-1.0.0.tar.gz` (sdist)
+
+### Requirements
+
+- Python ≥ 3.10
+- Streamlit ≥ 1.51
+- Node.js ≥ 24 (LTS) — only to build the frontend
+- [uv](https://docs.astral.sh/uv/) — used by the commands shown above
+
+## License
+
+Apache-2.0 (see [`LICENSE`](https://github.com/LelandGrunt/streamlit-listview/blob/HEAD/LICENSE)). Bundled/ported third-party code is attributed in [`NOTICE`](https://github.com/LelandGrunt/streamlit-listview/blob/HEAD/NOTICE).
+
+## AI
+
+Claude Code (Models Opus 4.8 / 5 / 5.5 and Fable 5) with superpowers plugin.