# streamlit-select-icons
A Streamlit custom component that creates a selectable grid of labeled icons with flexible layout options.
## Features
- ✅ **Grid-based layout system** (rows/columns)
- ✅ **Multi/single selection modes**
- ✅ **Responsive card sizing**
- ✅ **Per-item custom styling** (colors)
- ✅ **Bold selected labels**
- ✅ **Configurable component dimensions**
- ✅ **Row/column orientations with scrolling**
- ✅ **No icon support** (display items without images)
- ✅ **Alternative text display** (show text/emoji instead of icons)
## Installation
```sh
pip install streamlit-select-icons
```
## Usage
```python
import streamlit as st
from streamlit_select_icons import select_icons
# Define your items
items = {
"home": {
"label": "Home",
"icon": "static/home-icon.png", # Will resolve to /app/static/home-icon.png
"properties": {"category": "navigation"}
},
"search": {
"label": "Search",
"icon": "static/search-icon.png", # Will resolve to /app/static/search-icon.png
"properties": {"category": "action"}
},
"profile": {
"label": "Profile",
"icon": "static/profile-icon.png", # Will resolve to /app/static/profile-icon.png
"properties": {"category": "user"}
},
"status": {
"label": "Active",
"icon": None, # No icon - will show placeholder
"properties": {"category": "status"}
},
"priority": {
"label": "High Priority",
"icon": None, # No icon
"alt_text": "⚡", # Show emoji instead
"properties": {"category": "priority"}
},
}
# Create the icon selector
result = select_icons(
items=items,
multi_select=True, # Allow multiple selections
layout="column", # or "row"
columns=2, # Number of columns in grid
width=300, # Component width
height=200, # Component height
size=80, # Individual card size
bold_selected=True, # Bold labels when selected
key="icon_selector"
)
if result:
st.write("Selected items:", result["selected_items"])
st.write("All items:", result["items"])
```
## Icon Configuration
### With Icons
```python
"item_id": {
"label": "Item Label",
"icon": "static/icon.png", # Path to icon image
"properties": {...}
}
```
### Without Icons
```python
"item_id": {
"label": "Item Label",
"icon": None, # No icon - label text fills the icon area
"properties": {...}
}
```
### With Alternative Text
```python
"item_id": {
"label": "Item Label",
"icon": None, # No icon
"alt_text": "📝", # Text/emoji to display instead (larger than label)
"properties": {...}
}
```
**Note**: When both `icon` and `alt_text` are `None`, the component completely omits the icon area, displaying only the label text. This creates a cleaner, more focused appearance for text-only items.
## Static Files
The component automatically resolves icon paths that start with `static/` to Streamlit's `/app/static/` folder. This means:
- `"static/icon.png"` → `/app/static/icon.png`
- `"static/my-icon.svg"` → `/app/static/my-icon.svg`
**Important**: Place your icon images in your Streamlit app's `static/` folder for this to work correctly.
## Parameters
- **items**: Dictionary of items with id keys and item data
- **label**: Display text for the item
- **icon**: Path to icon image (can be `None` for no icon)
- **alt_text**: Text/emoji to display when icon is `None` (optional)
- **properties**: Additional metadata (optional)
- **selected_items**: List of pre-selected item IDs
- **multi_select**: Enable multiple selection (default: True)
- **layout**: "column" or "row" layout orientation
- **columns**: Number of columns (column layout)
- **rows**: Number of rows (row layout)
- **width**: Component container width in pixels
- **height**: Component container height in pixels
- **size**: Individual card size in pixels (default: 96)
- **item_style**: Per-item custom colors and styling
- **bold_selected**: Make selected labels bold (default: False)
- **key**: Unique component key
Raw data
{
"_id": null,
"home_page": null,
"name": "streamlit-select-icons",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "streamlit, component, icons, ui, selection",
"author": null,
"author_email": "Andrew Ferguson <afdatatech@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/30/5d/f696e1d263dc44bcfa600868330f44745308df5617b27ad3bc7a46567ea2/streamlit_select_icons-0.1.0.tar.gz",
"platform": null,
"description": "# streamlit-select-icons\r\n\r\nA Streamlit custom component that creates a selectable grid of labeled icons with flexible layout options.\r\n\r\n## Features\r\n\r\n- \u2705 **Grid-based layout system** (rows/columns)\r\n- \u2705 **Multi/single selection modes** \r\n- \u2705 **Responsive card sizing**\r\n- \u2705 **Per-item custom styling** (colors)\r\n- \u2705 **Bold selected labels**\r\n- \u2705 **Configurable component dimensions**\r\n- \u2705 **Row/column orientations with scrolling**\r\n- \u2705 **No icon support** (display items without images)\r\n- \u2705 **Alternative text display** (show text/emoji instead of icons)\r\n\r\n## Installation\r\n\r\n```sh\r\npip install streamlit-select-icons\r\n```\r\n\r\n## Usage\r\n\r\n```python\r\nimport streamlit as st\r\nfrom streamlit_select_icons import select_icons\r\n\r\n# Define your items\r\nitems = {\r\n \"home\": {\r\n \"label\": \"Home\", \r\n \"icon\": \"static/home-icon.png\", # Will resolve to /app/static/home-icon.png\r\n \"properties\": {\"category\": \"navigation\"}\r\n },\r\n \"search\": {\r\n \"label\": \"Search\", \r\n \"icon\": \"static/search-icon.png\", # Will resolve to /app/static/search-icon.png\r\n \"properties\": {\"category\": \"action\"}\r\n },\r\n \"profile\": {\r\n \"label\": \"Profile\", \r\n \"icon\": \"static/profile-icon.png\", # Will resolve to /app/static/profile-icon.png\r\n \"properties\": {\"category\": \"user\"}\r\n },\r\n \"status\": {\r\n \"label\": \"Active\", \r\n \"icon\": None, # No icon - will show placeholder\r\n \"properties\": {\"category\": \"status\"}\r\n },\r\n \"priority\": {\r\n \"label\": \"High Priority\", \r\n \"icon\": None, # No icon\r\n \"alt_text\": \"\u26a1\", # Show emoji instead\r\n \"properties\": {\"category\": \"priority\"}\r\n },\r\n}\r\n\r\n# Create the icon selector\r\nresult = select_icons(\r\n items=items,\r\n multi_select=True, # Allow multiple selections\r\n layout=\"column\", # or \"row\"\r\n columns=2, # Number of columns in grid\r\n width=300, # Component width\r\n height=200, # Component height\r\n size=80, # Individual card size\r\n bold_selected=True, # Bold labels when selected\r\n key=\"icon_selector\"\r\n)\r\n\r\nif result:\r\n st.write(\"Selected items:\", result[\"selected_items\"])\r\n st.write(\"All items:\", result[\"items\"])\r\n```\r\n\r\n## Icon Configuration\r\n\r\n### With Icons\r\n```python\r\n\"item_id\": {\r\n \"label\": \"Item Label\",\r\n \"icon\": \"static/icon.png\", # Path to icon image\r\n \"properties\": {...}\r\n}\r\n```\r\n\r\n### Without Icons\r\n```python\r\n\"item_id\": {\r\n \"label\": \"Item Label\",\r\n \"icon\": None, # No icon - label text fills the icon area\r\n \"properties\": {...}\r\n}\r\n```\r\n\r\n### With Alternative Text\r\n```python\r\n\"item_id\": {\r\n \"label\": \"Item Label\",\r\n \"icon\": None, # No icon\r\n \"alt_text\": \"\ud83d\udcdd\", # Text/emoji to display instead (larger than label)\r\n \"properties\": {...}\r\n}\r\n```\r\n\r\n**Note**: When both `icon` and `alt_text` are `None`, the component completely omits the icon area, displaying only the label text. This creates a cleaner, more focused appearance for text-only items.\r\n\r\n## Static Files\r\n\r\nThe component automatically resolves icon paths that start with `static/` to Streamlit's `/app/static/` folder. This means:\r\n\r\n- `\"static/icon.png\"` \u2192 `/app/static/icon.png`\r\n- `\"static/my-icon.svg\"` \u2192 `/app/static/my-icon.svg`\r\n\r\n**Important**: Place your icon images in your Streamlit app's `static/` folder for this to work correctly.\r\n\r\n## Parameters\r\n\r\n- **items**: Dictionary of items with id keys and item data\r\n - **label**: Display text for the item\r\n - **icon**: Path to icon image (can be `None` for no icon)\r\n - **alt_text**: Text/emoji to display when icon is `None` (optional)\r\n - **properties**: Additional metadata (optional)\r\n- **selected_items**: List of pre-selected item IDs\r\n- **multi_select**: Enable multiple selection (default: True)\r\n- **layout**: \"column\" or \"row\" layout orientation\r\n- **columns**: Number of columns (column layout)\r\n- **rows**: Number of rows (row layout) \r\n- **width**: Component container width in pixels\r\n- **height**: Component container height in pixels\r\n- **size**: Individual card size in pixels (default: 96)\r\n- **item_style**: Per-item custom colors and styling\r\n- **bold_selected**: Make selected labels bold (default: False)\r\n- **key**: Unique component key\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Streamlit component that creates a selectable list of icons with labels.",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/edt-andrew/streamlit-select-icons/issues",
"Homepage": "https://github.com/edt-andrew/streamlit-select-icons",
"Source": "https://github.com/edt-andrew/streamlit-select-icons"
},
"split_keywords": [
"streamlit",
" component",
" icons",
" ui",
" selection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f1c0233f0ed10b8a2beccb4d985428c079ca7d37e215e123544c38b2a8578b89",
"md5": "bed431ea7263077e638d6203b01cf1af",
"sha256": "1bfc69eb023c836ed1114cf446ed2b977fcef8b70bafebb86571aa28c5c40bd6"
},
"downloads": -1,
"filename": "streamlit_select_icons-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bed431ea7263077e638d6203b01cf1af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 127262,
"upload_time": "2025-09-01T11:44:21",
"upload_time_iso_8601": "2025-09-01T11:44:21.052765Z",
"url": "https://files.pythonhosted.org/packages/f1/c0/233f0ed10b8a2beccb4d985428c079ca7d37e215e123544c38b2a8578b89/streamlit_select_icons-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "305df696e1d263dc44bcfa600868330f44745308df5617b27ad3bc7a46567ea2",
"md5": "359d8261c54ce2404aaaa85dbfe93695",
"sha256": "118df7ce94c6d07d4476026996adb76000f917534b8382997b13f3eb1cd110de"
},
"downloads": -1,
"filename": "streamlit_select_icons-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "359d8261c54ce2404aaaa85dbfe93695",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 128794,
"upload_time": "2025-09-01T11:44:22",
"upload_time_iso_8601": "2025-09-01T11:44:22.539995Z",
"url": "https://files.pythonhosted.org/packages/30/5d/f696e1d263dc44bcfa600868330f44745308df5617b27ad3bc7a46567ea2/streamlit_select_icons-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 11:44:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "edt-andrew",
"github_project": "streamlit-select-icons",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "streamlit-select-icons"
}
JSON
