streamlit-sortable-multiselect 0.7.5__tar.gz → 0.7.6__tar.gz

{streamlit_sortable_multiselect-0.7.5/streamlit_sortable_multiselect.egg-info → streamlit_sortable_multiselect-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: streamlit-sortable-multiselect
-Version: 0.7.5
+Version: 0.7.6
 Summary: A Streamlit custom component for selecting and reordering multiple string values.
 Author: Kentaro Aoki
 License-Expression: MIT
@@ -101,8 +101,12 @@ st.write(selected)
 | `disabled` | `bool` | `False` | Disables searching, selecting, removing, dragging, and move buttons. |
 | `show_move_buttons` | `bool` | `True` | Shows up/down buttons on selected items. Drag sorting remains available unless `disabled=True`. |
 | `show_numbers` | `bool` | `False` | Shows 1-based position numbers before selected item labels. |
-| `base_color` | `str \| None` | `None` | Background color applied to all selected items. Accepts CSS color values such as `"#eef2ff"` or `"lightblue"`. |
-| `order_colors` | `Mapping[int, str] \| None` | `None` | Per-position selected item background colors. Keys are 1-based positions, for example `{1: "#fee2e2", 2: "#dcfce7"}`. These override `base_color` for matching positions. |
+| `base_color` | `str \| Mapping[str, str] \| None` | `None` | Fallback color for every selected item. See [Colors](#colors). |
+| `order_colors` | `Mapping[int, str \| Mapping[str, str]] \| None` | `None` | Per-position colors. Positive keys count from the top (`1` is first), negative keys count from the bottom (`-1` is last), for example `{1: "#fee2e2", -1: "#dcfce7"}`. |
+| `value_colors` | `Mapping[str, str \| Mapping[str, str]] \| None` | `None` | Per-value colors keyed by option value, for example `{"python": "#3776ab"}`. These follow an item as it is reordered. |
+| `color_palette` | `Sequence[str \| Mapping[str, str]] \| None` | `None` | Colors cycled across selected positions. Position 1 uses the first entry and the palette repeats for longer selections. |
+| `color_priority` | `Sequence[str] \| None` | `None` | Ranking of the color sources `"value"`, `"option"`, `"order"`, `"palette"`, and `"base"`. Omitted sources keep their default rank. |
+| `tooltip_color` | `str \| Mapping[str, str] \| None` | `None` | Color of the tooltip shown for labels that do not fit. `None` uses the built-in dark tooltip. See [Labels](#labels). |
 | `max_selections` | `int \| None` | `None` | Maximum number of selected items. `None` means no limit. Use `0` to prevent any selections. |
 | `max_selections_placeholder` | `str` | `"Selection limit reached"` | Placeholder shown when `max_selections` has been reached. This takes precedence over `placeholder` and `no_options_placeholder`. |
 | `empty_message` | `str` | `"No items selected"` | Message shown where the selected list appears when no items are selected. |
@@ -116,6 +120,7 @@ st.write(selected)
 | `suggestions_label_path` | `str` | `"label"` | Dot-separated path to each suggestion's display label. |
 | `suggestions_value_path` | `str` | `"value"` | Dot-separated path to each suggestion's returned value. |
 | `suggestions_icon_url_path` | `str \| None` | `"icon_url"` | Optional dot-separated path to each suggestion's icon URL. `None` disables API icons. |
+| `suggestions_color_path` | `str \| None` | `None` | Optional dot-separated path to each suggestion's color. The value may be a CSS color string or a mapping of color fields. `None` disables API colors. |
 | `suggestions_headers` | `Mapping[str, str] \| None` | `None` | HTTP headers sent with suggestions requests. Header values are visible to browser users and must not contain secrets. |
 | `suggestions_min_chars` | `int` | `1` | Minimum trimmed query length before requesting suggestions. Use `0` to allow an empty query. |
 | `suggestions_debounce_ms` | `int` | `300` | Delay in milliseconds between the latest input and the API request. |
@@ -126,10 +131,106 @@ st.write(selected)
 Option dictionaries use this shape:
 
 ```python
-{"label": "Python", "value": "python", "icon_url": "https://www.python.org/static/favicon.ico"}
+{
+    "label": "Python",
+    "value": "python",
+    "icon_url": "https://www.python.org/static/favicon.ico",
+    "color": "#3776ab",
+}
+```
+
+`icon_url` and `color` may be omitted. The returned value is always the `value`, not the display `label`.
+
+## Colors
+
+Anywhere a color is accepted, pass either a CSS color string or a mapping that sets
+any subset of `background`, `text`, and `border`:
+
+```python
+"#fee2e2"
+{"background": "#111827", "text": "#facc15", "border": "#f74c00"}
+```
+
+A string sets the background. When `text` is not set, the component picks black or
+white for readability against the resolved background.
+
+Colors come from five sources. Each source contributes a color, and the highest
+ranked source that sets a field wins that field, so a value color that sets only
+`text` still inherits the background from `base_color`:
+
+| Source | Set with | Keyed by |
+| --- | --- | --- |
+| `value` | `value_colors` | Option value. Follows the item as it is reordered. |
+| `option` | `color` in an option dictionary, or `suggestions_color_path` | The option itself. |
+| `order` | `order_colors` | Selected position. `1` is first, `-1` is last. |
+| `palette` | `color_palette` | Selected position, cycling through the palette. |
+| `base` | `base_color` | Every selected item. |
+
+The default ranking is the table order. Reorder it with `color_priority`; sources you
+leave out keep their default rank, so `color_priority=["order"]` only promotes
+position colors above everything else.
+
+When a positive and a negative `order_colors` key address the same slot, such as `1`
+and `-3` in a three item list, the positive key wins. Every color must set at least
+one field: `None` and `{}` are rejected rather than ignored, so a mistyped color
+surfaces as an error instead of silently doing nothing.
+
+```python
+selected = sortable_multiselect(
+    "Podium",
+    options=[
+        {"label": "Python", "value": "python", "color": "#3776ab"},
+        {"label": "Rust", "value": "rust"},
+        {"label": "Go", "value": "go"},
+    ],
+    default=["python", "rust", "go"],
+    # Gold, silver, and bronze by position, ranked above each option's own color.
+    order_colors={
+        1: {"background": "#fde68a", "border": "#f59e0b"},
+        2: {"background": "#e5e7eb", "border": "#9ca3af"},
+        -1: {"background": "#fed7aa", "border": "#ea580c"},
+    },
+    color_priority=["order"],
+)
 ```
 
-`icon_url` may be omitted. The returned value is always the `value`, not the display `label`.
+Options that resolve to a color show a small swatch in the options dropdown.
+
+Because an option's `value` is its id, `value_colors` binds a color to an item rather
+than to a slot. `examples/color_by_id.py` puts both side by side: two lists holding the
+same items, one colored by position and one colored by id. Dragging an item in each
+shows position colors staying with the slot while id colors travel with the item.
+
+## Labels
+
+Option labels in the dropdown are shown on one line and cut off with an ellipsis when
+they do not fit. Hovering a cut-off label shows the full text in a tooltip anchored to
+that label, and labels that fit are left without one. Selected item labels wrap onto
+multiple lines instead of being cut off, so they only get a tooltip if surrounding
+styles clip them.
+
+The tooltip is drawn by the component rather than by the browser's native `title`, so
+it is styled with the rest of the component, appears after a short delay instead of
+about a second, and flips above or below the label to stay inside the component frame.
+It disappears as soon as the pointer leaves, the list scrolls, or the row it points at
+changes. Screen readers are unaffected either way: a clipped label is cut off visually
+but its full text is always in the DOM.
+
+`tooltip_color` restyles it, using the same color form as everything above. A string
+sets the background and the text follows for contrast; a mapping may also set `text`
+and `border`. Because the component renders inside an iframe, this argument is the only
+way to change the tooltip: styles from the surrounding app cannot reach it.
+
+```python
+tooltip_color="#1e3a8a"                                              # white text follows
+tooltip_color={"background": "#ffffff", "text": "#111827", "border": "#d1d5db"}
+```
+
+A light tooltip needs a `border` to separate it from the content behind it. The arrow
+picks up both the background and the border, so it stays attached either way.
+
+`examples/tooltip_labels.py` shows the same options in a narrow list and a wide one,
+so the conditional behavior is visible side by side.
 
 ## API Suggestions
 
@@ -190,6 +291,8 @@ Run the example app:
 
 ```bash
 streamlit run examples/basic.py
+streamlit run examples/color_by_id.py
+streamlit run examples/tooltip_labels.py
 streamlit run examples/api_suggestions.py
 ```
 

{streamlit_sortable_multiselect-0.7.5 → streamlit_sortable_multiselect-0.7.6}/README.md

@@ -73,8 +73,12 @@ st.write(selected)
 | `disabled` | `bool` | `False` | Disables searching, selecting, removing, dragging, and move buttons. |
 | `show_move_buttons` | `bool` | `True` | Shows up/down buttons on selected items. Drag sorting remains available unless `disabled=True`. |
 | `show_numbers` | `bool` | `False` | Shows 1-based position numbers before selected item labels. |
-| `base_color` | `str \| None` | `None` | Background color applied to all selected items. Accepts CSS color values such as `"#eef2ff"` or `"lightblue"`. |
-| `order_colors` | `Mapping[int, str] \| None` | `None` | Per-position selected item background colors. Keys are 1-based positions, for example `{1: "#fee2e2", 2: "#dcfce7"}`. These override `base_color` for matching positions. |
+| `base_color` | `str \| Mapping[str, str] \| None` | `None` | Fallback color for every selected item. See [Colors](#colors). |
+| `order_colors` | `Mapping[int, str \| Mapping[str, str]] \| None` | `None` | Per-position colors. Positive keys count from the top (`1` is first), negative keys count from the bottom (`-1` is last), for example `{1: "#fee2e2", -1: "#dcfce7"}`. |
+| `value_colors` | `Mapping[str, str \| Mapping[str, str]] \| None` | `None` | Per-value colors keyed by option value, for example `{"python": "#3776ab"}`. These follow an item as it is reordered. |
+| `color_palette` | `Sequence[str \| Mapping[str, str]] \| None` | `None` | Colors cycled across selected positions. Position 1 uses the first entry and the palette repeats for longer selections. |
+| `color_priority` | `Sequence[str] \| None` | `None` | Ranking of the color sources `"value"`, `"option"`, `"order"`, `"palette"`, and `"base"`. Omitted sources keep their default rank. |
+| `tooltip_color` | `str \| Mapping[str, str] \| None` | `None` | Color of the tooltip shown for labels that do not fit. `None` uses the built-in dark tooltip. See [Labels](#labels). |
 | `max_selections` | `int \| None` | `None` | Maximum number of selected items. `None` means no limit. Use `0` to prevent any selections. |
 | `max_selections_placeholder` | `str` | `"Selection limit reached"` | Placeholder shown when `max_selections` has been reached. This takes precedence over `placeholder` and `no_options_placeholder`. |
 | `empty_message` | `str` | `"No items selected"` | Message shown where the selected list appears when no items are selected. |
@@ -88,6 +92,7 @@ st.write(selected)
 | `suggestions_label_path` | `str` | `"label"` | Dot-separated path to each suggestion's display label. |
 | `suggestions_value_path` | `str` | `"value"` | Dot-separated path to each suggestion's returned value. |
 | `suggestions_icon_url_path` | `str \| None` | `"icon_url"` | Optional dot-separated path to each suggestion's icon URL. `None` disables API icons. |
+| `suggestions_color_path` | `str \| None` | `None` | Optional dot-separated path to each suggestion's color. The value may be a CSS color string or a mapping of color fields. `None` disables API colors. |
 | `suggestions_headers` | `Mapping[str, str] \| None` | `None` | HTTP headers sent with suggestions requests. Header values are visible to browser users and must not contain secrets. |
 | `suggestions_min_chars` | `int` | `1` | Minimum trimmed query length before requesting suggestions. Use `0` to allow an empty query. |
 | `suggestions_debounce_ms` | `int` | `300` | Delay in milliseconds between the latest input and the API request. |
@@ -98,10 +103,106 @@ st.write(selected)
 Option dictionaries use this shape:
 
 ```python
-{"label": "Python", "value": "python", "icon_url": "https://www.python.org/static/favicon.ico"}
+{
+    "label": "Python",
+    "value": "python",
+    "icon_url": "https://www.python.org/static/favicon.ico",
+    "color": "#3776ab",
+}
+```
+
+`icon_url` and `color` may be omitted. The returned value is always the `value`, not the display `label`.
+
+## Colors
+
+Anywhere a color is accepted, pass either a CSS color string or a mapping that sets
+any subset of `background`, `text`, and `border`:
+
+```python
+"#fee2e2"
+{"background": "#111827", "text": "#facc15", "border": "#f74c00"}
+```
+
+A string sets the background. When `text` is not set, the component picks black or
+white for readability against the resolved background.
+
+Colors come from five sources. Each source contributes a color, and the highest
+ranked source that sets a field wins that field, so a value color that sets only
+`text` still inherits the background from `base_color`:
+
+| Source | Set with | Keyed by |
+| --- | --- | --- |
+| `value` | `value_colors` | Option value. Follows the item as it is reordered. |
+| `option` | `color` in an option dictionary, or `suggestions_color_path` | The option itself. |
+| `order` | `order_colors` | Selected position. `1` is first, `-1` is last. |
+| `palette` | `color_palette` | Selected position, cycling through the palette. |
+| `base` | `base_color` | Every selected item. |
+
+The default ranking is the table order. Reorder it with `color_priority`; sources you
+leave out keep their default rank, so `color_priority=["order"]` only promotes
+position colors above everything else.
+
+When a positive and a negative `order_colors` key address the same slot, such as `1`
+and `-3` in a three item list, the positive key wins. Every color must set at least
+one field: `None` and `{}` are rejected rather than ignored, so a mistyped color
+surfaces as an error instead of silently doing nothing.
+
+```python
+selected = sortable_multiselect(
+    "Podium",
+    options=[
+        {"label": "Python", "value": "python", "color": "#3776ab"},
+        {"label": "Rust", "value": "rust"},
+        {"label": "Go", "value": "go"},
+    ],
+    default=["python", "rust", "go"],
+    # Gold, silver, and bronze by position, ranked above each option's own color.
+    order_colors={
+        1: {"background": "#fde68a", "border": "#f59e0b"},
+        2: {"background": "#e5e7eb", "border": "#9ca3af"},
+        -1: {"background": "#fed7aa", "border": "#ea580c"},
+    },
+    color_priority=["order"],
+)
 ```
 
-`icon_url` may be omitted. The returned value is always the `value`, not the display `label`.
+Options that resolve to a color show a small swatch in the options dropdown.
+
+Because an option's `value` is its id, `value_colors` binds a color to an item rather
+than to a slot. `examples/color_by_id.py` puts both side by side: two lists holding the
+same items, one colored by position and one colored by id. Dragging an item in each
+shows position colors staying with the slot while id colors travel with the item.
+
+## Labels
+
+Option labels in the dropdown are shown on one line and cut off with an ellipsis when
+they do not fit. Hovering a cut-off label shows the full text in a tooltip anchored to
+that label, and labels that fit are left without one. Selected item labels wrap onto
+multiple lines instead of being cut off, so they only get a tooltip if surrounding
+styles clip them.
+
+The tooltip is drawn by the component rather than by the browser's native `title`, so
+it is styled with the rest of the component, appears after a short delay instead of
+about a second, and flips above or below the label to stay inside the component frame.
+It disappears as soon as the pointer leaves, the list scrolls, or the row it points at
+changes. Screen readers are unaffected either way: a clipped label is cut off visually
+but its full text is always in the DOM.
+
+`tooltip_color` restyles it, using the same color form as everything above. A string
+sets the background and the text follows for contrast; a mapping may also set `text`
+and `border`. Because the component renders inside an iframe, this argument is the only
+way to change the tooltip: styles from the surrounding app cannot reach it.
+
+```python
+tooltip_color="#1e3a8a"                                              # white text follows
+tooltip_color={"background": "#ffffff", "text": "#111827", "border": "#d1d5db"}
+```
+
+A light tooltip needs a `border` to separate it from the content behind it. The arrow
+picks up both the background and the border, so it stays attached either way.
+
+`examples/tooltip_labels.py` shows the same options in a narrow list and a wide one,
+so the conditional behavior is visible side by side.
 
 ## API Suggestions
 
@@ -162,6 +263,8 @@ Run the example app:
 
 ```bash
 streamlit run examples/basic.py
+streamlit run examples/color_by_id.py
+streamlit run examples/tooltip_labels.py
 streamlit run examples/api_suggestions.py
 ```
 

{streamlit_sortable_multiselect-0.7.5 → streamlit_sortable_multiselect-0.7.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "streamlit-sortable-multiselect"
-version = "0.7.5"
+version = "0.7.6"
 description = "A Streamlit custom component for selecting and reordering multiple string values."
 readme = "README.md"
 requires-python = ">=3.9"

{streamlit_sortable_multiselect-0.7.5 → streamlit_sortable_multiselect-0.7.6}/streamlit_sortable_multiselect/__init__.py

@@ -4,18 +4,29 @@ from __future__ import annotations
 
 import os
 from pathlib import Path
-from typing import Any, Iterable, Mapping, Sequence, cast
+from typing import Any, Iterable, Mapping, Sequence, Union, cast
 from urllib.parse import urlparse
 
 import streamlit.components.v1 as components
 
-__version__ = "0.7.5"
-__all__ = ["sortable_multiselect"]
+__version__ = "0.7.6"
+__all__ = ["COLOR_FIELDS", "COLOR_SOURCES", "ColorValue", "sortable_multiselect"]
 
 _COMPONENT_NAME = "streamlit_sortable_multiselect"
 _DEV_SERVER_URL = "http://localhost:5173"
 _RELEASE = os.environ.get("STREAMLIT_SORTABLE_MULTISELECT_DEV") != "1"
 
+#: A color is either a CSS color string (used as the background) or a mapping
+#: that sets any subset of the fields in :data:`COLOR_FIELDS`.
+ColorValue = Union[str, Mapping[str, str]]
+
+#: Styleable parts of a selected item.
+COLOR_FIELDS = ("background", "text", "border")
+
+#: Color sources, in default precedence order. Each source contributes a color
+#: spec, and the highest-priority source that sets a field wins that field.
+COLOR_SOURCES = ("value", "option", "order", "palette", "base")
+
 
 def _declare_component():
     if _RELEASE:
@@ -40,11 +51,52 @@ def _validate_string_sequence(name: str, values: Sequence[str] | None) -> list[s
     return result
 
 
-def _normalize_options(options: Sequence[str | Mapping[str, Any]]) -> list[dict[str, str | None]]:
+def _normalize_color(name: str, color: ColorValue | None) -> dict[str, str] | None:
+    """Return a color as a field mapping, or None when nothing is set."""
+    if color is None:
+        return None
+    if isinstance(color, str):
+        if not color:
+            raise ValueError(f"{name} must not be an empty color string.")
+        return {"background": color}
+    if not isinstance(color, Mapping):
+        raise TypeError(
+            f"{name} must be a CSS color string or a mapping with any of: "
+            f"{', '.join(COLOR_FIELDS)}."
+        )
+
+    spec: dict[str, str] = {}
+    for field, field_value in color.items():
+        if field not in COLOR_FIELDS:
+            raise ValueError(
+                f"{name} contains an unknown color field {field!r}. "
+                f"Use any of: {', '.join(COLOR_FIELDS)}."
+            )
+        if not isinstance(field_value, str):
+            raise TypeError(f"{name} color fields must be strings.")
+        if not field_value:
+            raise ValueError(f"{name} color fields must not be empty.")
+        spec[field] = field_value
+    return spec or None
+
+
+def _require_color(name: str, color: ColorValue | None) -> dict[str, str]:
+    """Return a color that must actually set something."""
+    if color is None:
+        raise TypeError(f"{name} must be a color, not None.")
+    spec = _normalize_color(name, color)
+    if spec is None:
+        raise ValueError(f"{name} must set at least one of: {', '.join(COLOR_FIELDS)}.")
+    return spec
+
+
+def _normalize_options(
+    options: Sequence[str | Mapping[str, Any]],
+) -> list[dict[str, Any]]:
     if isinstance(options, str) or not isinstance(options, Iterable):
         raise TypeError("options must be a sequence of strings or option dictionaries.")
 
-    normalized_options: list[dict[str, str | None]] = []
+    normalized_options: list[dict[str, Any]] = []
     for option in options:
         if isinstance(option, str):
             normalized_options.append({"label": option, "value": option, "icon_url": None})
@@ -63,26 +115,94 @@ def _normalize_options(options: Sequence[str | Mapping[str, Any]]) -> list[dict[
         if icon_url is not None and not isinstance(icon_url, str):
             raise TypeError("option icon_url must be a string or None.")
 
-        normalized_options.append({"label": label, "value": value, "icon_url": icon_url})
+        normalized_option: dict[str, Any] = {
+            "label": label,
+            "value": value,
+            "icon_url": icon_url,
+        }
+        # Omitted rather than sent as null: with tens of thousands of options this
+        # key alone is a fifth of the payload the browser has to receive.
+        if "color" in option:
+            normalized_option["color"] = _require_color(
+                f"option color for {value!r}", option["color"]
+            )
+        normalized_options.append(normalized_option)
 
     return normalized_options
 
 
-def _validate_order_colors(order_colors: Mapping[int, str] | None) -> dict[int, str]:
+def _validate_order_colors(
+    order_colors: Mapping[int, ColorValue] | None,
+) -> dict[int, dict[str, str]]:
     if order_colors is None:
         return {}
     if not isinstance(order_colors, Mapping):
-        raise TypeError("order_colors must be a mapping of 1-based positions to color strings.")
+        raise TypeError("order_colors must be a mapping of positions to colors.")
 
-    result: dict[int, str] = {}
+    result: dict[int, dict[str, str]] = {}
     for position, color in order_colors.items():
-        if not isinstance(position, int):
+        if isinstance(position, bool) or not isinstance(position, int):
             raise TypeError("order_colors keys must be integers.")
-        if position < 1:
-            raise ValueError("order_colors keys must be 1 or greater.")
-        if not isinstance(color, str):
-            raise TypeError("order_colors values must be strings.")
-        result[position] = color
+        if position == 0:
+            raise ValueError(
+                "order_colors keys must be non-zero integers. "
+                "Positive keys count from the top, negative keys count from the bottom."
+            )
+        result[position] = _require_color(f"order_colors[{position}]", color)
+    return result
+
+
+def _validate_value_colors(
+    value_colors: Mapping[str, ColorValue] | None,
+) -> dict[str, dict[str, str]]:
+    if value_colors is None:
+        return {}
+    if not isinstance(value_colors, Mapping):
+        raise TypeError("value_colors must be a mapping of option values to colors.")
+
+    result: dict[str, dict[str, str]] = {}
+    for value, color in value_colors.items():
+        if not isinstance(value, str):
+            raise TypeError("value_colors keys must be strings.")
+        result[value] = _require_color(f"value_colors[{value!r}]", color)
+    return result
+
+
+def _validate_color_palette(
+    color_palette: Sequence[ColorValue] | None,
+) -> list[dict[str, str]]:
+    if color_palette is None:
+        return []
+    if isinstance(color_palette, (str, Mapping)) or not isinstance(color_palette, Iterable):
+        raise TypeError("color_palette must be a sequence of colors.")
+
+    return [
+        _require_color(f"color_palette[{index}]", color)
+        for index, color in enumerate(color_palette)
+    ]
+
+
+def _validate_color_priority(color_priority: Sequence[str] | None) -> list[str]:
+    if color_priority is None:
+        return list(COLOR_SOURCES)
+    if isinstance(color_priority, str) or not isinstance(color_priority, Iterable):
+        raise TypeError("color_priority must be a sequence of color source names.")
+
+    result: list[str] = []
+    for source in color_priority:
+        if not isinstance(source, str):
+            raise TypeError("color_priority must contain only strings.")
+        if source not in COLOR_SOURCES:
+            raise ValueError(
+                f"color_priority contains an unknown color source {source!r}. "
+                f"Use any of: {', '.join(COLOR_SOURCES)}."
+            )
+        if source in result:
+            raise ValueError(f"color_priority must not repeat {source!r}.")
+        result.append(source)
+
+    # Sources the caller left out still apply, ranked below the listed ones.
+    result.extend(source for source in COLOR_SOURCES if source not in result)
     return result
 
 
@@ -173,8 +293,8 @@ def sortable_multiselect(
     disabled: bool = False,
     show_move_buttons: bool = True,
     show_numbers: bool = False,
-    base_color: str | None = None,
-    order_colors: Mapping[int, str] | None = None,
+    base_color: ColorValue | None = None,
+    order_colors: Mapping[int, ColorValue] | None = None,
     max_selections: int | None = None,
     max_selections_placeholder: str = "Selection limit reached",
     empty_message: str = "No items selected",
@@ -193,6 +313,11 @@ def sortable_multiselect(
     suggestions_debounce_ms: int = 300,
     suggestions_loading_message: str = "Loading suggestions...",
     suggestions_error_message: str = "Failed to load suggestions",
+    value_colors: Mapping[str, ColorValue] | None = None,
+    color_palette: Sequence[ColorValue] | None = None,
+    color_priority: Sequence[str] | None = None,
+    tooltip_color: ColorValue | None = None,
+    suggestions_color_path: str | None = None,
     key: str | None = None,
 ) -> list[str]:
     """Select multiple string values and return them in user-defined order.
@@ -202,7 +327,8 @@ def sortable_multiselect(
     label:
         Text label rendered above the component.
     options:
-        Available string values, or dictionaries with label, value, and optional icon_url.
+        Available string values, or dictionaries with label, value, and optional
+        icon_url and color.
     default:
         Initially selected values, in the desired initial order.
     placeholder:
@@ -214,9 +340,11 @@ def sortable_multiselect(
     show_numbers:
         Show 1-based numbers before selected items.
     base_color:
-        Background color applied to selected items.
+        Fallback color for every selected item. A CSS color string sets the background;
+        a mapping may set any of "background", "text", and "border".
     order_colors:
-        Per-position background colors keyed by 1-based selected item position.
+        Per-position colors keyed by selected item position. Positive keys count from
+        the top (1 is first), negative keys count from the bottom (-1 is last).
     max_selections:
         Maximum number of selected items. None means no limit.
     max_selections_placeholder:
@@ -253,6 +381,20 @@ def sortable_multiselect(
         Text shown while suggestions are loading.
     suggestions_error_message:
         Text shown when suggestions cannot be loaded.
+    value_colors:
+        Per-value colors keyed by option value. These follow an item as it is reordered.
+    color_palette:
+        Colors cycled across selected positions. Position 1 uses the first entry, and
+        the palette repeats once there are more items than entries.
+    color_priority:
+        Ranking of the color sources "value", "option", "order", "palette", and "base".
+        Earlier sources win, field by field. Omitted sources keep their default rank.
+    tooltip_color:
+        Color of the tooltip shown for labels that do not fit. A string sets the
+        background and the text follows for contrast; a mapping may also set "text"
+        and "border". None uses the built-in dark tooltip.
+    suggestions_color_path:
+        Optional dot-separated path to each suggestion's color. None disables API colors.
     key:
         Optional Streamlit component key.
     """
@@ -276,13 +418,18 @@ def sortable_multiselect(
         raise TypeError("show_move_buttons must be a bool.")
     if not isinstance(show_numbers, bool):
         raise TypeError("show_numbers must be a bool.")
-    if base_color is not None and not isinstance(base_color, str):
-        raise TypeError("base_color must be a string or None.")
 
+    base_color_value = None if base_color is None else _require_color("base_color", base_color)
+    tooltip_color_value = (
+        None if tooltip_color is None else _require_color("tooltip_color", tooltip_color)
+    )
     option_items = _normalize_options(options)
     option_values = [option["value"] for option in option_items]
     default_values = _validate_string_sequence("default", default)
     order_color_values = _validate_order_colors(order_colors)
+    value_color_values = _validate_value_colors(value_colors)
+    color_palette_values = _validate_color_palette(color_palette)
+    color_priority_values = _validate_color_priority(color_priority)
     max_selection_count = _validate_max_selections(max_selections)
     icon_size_value = _validate_icon_size(icon_size)
     options_max_height_value = _validate_options_max_height(options_max_height)
@@ -301,6 +448,9 @@ def sortable_multiselect(
     suggestions_icon_url_path_value = _validate_optional_non_empty_string(
         "suggestions_icon_url_path", suggestions_icon_url_path
     )
+    suggestions_color_path_value = _validate_optional_non_empty_string(
+        "suggestions_color_path", suggestions_color_path
+    )
     suggestions_headers_value = _normalize_suggestions_headers(suggestions_headers)
     suggestions_min_chars_value = _validate_non_negative_int(
         "suggestions_min_chars", suggestions_min_chars
@@ -351,8 +501,12 @@ def sortable_multiselect(
         disabled=disabled,
         show_move_buttons=show_move_buttons,
         show_numbers=show_numbers,
-        base_color=base_color,
+        base_color=base_color_value,
         order_colors=order_color_values,
+        value_colors=value_color_values,
+        color_palette=color_palette_values,
+        color_priority=color_priority_values,
+        tooltip_color=tooltip_color_value,
         max_selections=max_selection_count,
         max_selections_placeholder=max_selections_placeholder,
         empty_message=empty_message,
@@ -366,6 +520,7 @@ def sortable_multiselect(
         suggestions_label_path=suggestions_label_path_value,
         suggestions_value_path=suggestions_value_path_value,
         suggestions_icon_url_path=suggestions_icon_url_path_value,
+        suggestions_color_path=suggestions_color_path_value,
         suggestions_headers=suggestions_headers_value,
         suggestions_min_chars=suggestions_min_chars_value,
         suggestions_debounce_ms=suggestions_debounce_ms_value,