Streamlit Selectable Grid

A Streamlit component that displays a selectable grid of cells with support for headers, row indices, and custom styling options.

Requires Python 3.10 or newer and Streamlit 1.51 or newer.

Installation

pip install st-selectable-grid

Usage

import streamlit as st
from st_selectable_grid import st_selectable_grid

# Create a grid with header and index
cells = [
    [
        {"label": "A1", "cell_color": "#f0f8ff", "tooltip": "Cell A1", "mark": True},
        {"label": "<b>A2</b>", "cell_color": "#e6e6fa", "html": True},
        {"label": "A3", "cell_color": "#f5f5dc"}
    ],
    [
        {"label": "B1", "cell_color": "#f0ffff"},
        {"label": "<span style='color:red'>B2</span>", "cell_color": "#f5f5f5", "html": True},
        {"label": "B3", "cell_color": "#fffaf0"}
    ],
    [
        {"label": "C1", "cell_color": "#fff0f5"},
        {"label": "C2", "cell_color": "#f0f0f0"},
        {"label": "<i>C3</i>", "cell_color": "#fffff0", "html": True}
    ]
]

header = [
    {"label": "Column 1", "cell_color": "#e0e0e0", "mark": True},
    {"label": "Column 2", "cell_color": "#e0e0e0"},
    {"label": "Column 3", "cell_color": "#e0e0e0"}
]

index = ["Row 1", "Row 2", "Row 3"]

selection = st_selectable_grid(
    cells=cells,
    header=header,
    index=index,
    aspect_ratio=1.0,
    allow_secondary_selection=True,
    allow_header_selection=True,
    height=300,
    grid_position="center",
    resize=True,
    mark_color="#2196F3",
    primary_selection_color="#2196F3",
    secondary_selection_color="#FF9800",
    key="grid1"
)

if selection:
    if "primary" in selection:
        st.write("Primary selection (left click):", selection["primary"])
    if "secondary" in selection:
        st.write("Secondary selection (right click):", selection["secondary"])

Features

• Interactive grid with selectable cells
• Support for headers and row indices
• Customizable cell colors and aspect ratio
• Primary (left-click) and secondary (right-click) selections
• Tooltips on hover
• Cell marking with indicator dots
• Responsive design with positioning options
• Fixed or flexible sizing options
• HTML formatting support for cell content

Parameters

Cell Dictionary Format

Each cell can be either a string (which becomes the label) or a dictionary with these keys:

• label (str): The text to display in the cell
• cell_color (str): Background color in CSS format (e.g., "#f0f8ff" or "red")
• tooltip (str): Text to display when hovering over the cell
• mark (bool): If True, shows a marker dot in the top-right corner of the cell
• html (bool): If True, renders the label content as HTML, allowing formatting tags

HTML Formatting Example

You can use HTML tags in cell labels when the html flag is set to True:

cells = [
    [
        {"label": "Normal Text"},
        {"label": "<b>Bold Text</b>", "html": True},
        {"label": "<span style='color:red'>Red Text</span>", "html": True}
    ],
    [
        {"label": "<i>Italic</i>", "html": True},
        {"label": "<b>Bold</b> and <i>italic</i>", "html": True},
        {"label": "<u>Underlined</u>", "html": True}
    ]
]

Security Note: Use caution when setting html=True with untrusted content, as this could introduce security vulnerabilities.

Return Value

{
    "primary": {"x": col_index, "y": row_index},  # For left-click selection
    "secondary": {"x": col_index, "y": row_index}  # For right-click selection (if enabled)
}

Secondary selection is only available after a primary selection has been made unless allow_secondary_selection_first=True.

Local example testing

1. Clone and enter the repo:

   git clone https://github.com/hoggatt/st-selectable-grid.git
   cd st-selectable-grid
   

2. Create and activate a virtual environment (optional but recommended):

   python -m venv venv
   # On Windows
   venv\Scripts\activate
   # On macOS/Linux
   source venv/bin/activate
   

3. Install Python and frontend dependencies:

   pip install -e .
   npm --prefix st_selectable_grid/frontend install
   

4. Build the frontend assets:

   npm --prefix st_selectable_grid/frontend run build
   

5. From the repo root, run the example against this checkout:

   PYTHONPATH="$PWD" streamlit run st_selectable_grid/example.py
   

The PYTHONPATH="$PWD" prefix prevents Streamlit from importing an already-installed st-selectable-grid package instead of your local files.

While editing frontend files, run this in another terminal:

npm --prefix st_selectable_grid/frontend run dev

The v2 component loads from st_selectable_grid/frontend/build; npm run dev rebuilds that directory as files change.