Preparing 0.3.10-beta.1

Refined multi-select
Stable multi-select implementation
2026-11-11 12:48:19 +00:00 · 2026-01-04 21:22:53 +08:00 · 2026-01-04 19:21:07 +08:00 · 2026-01-04 14:39:32 +08:00 · 2026-01-03 14:24:08 +08:00 · 2026-01-03 14:21:35 +08:00
13 changed files with 449 additions and 93 deletions
@@ -0,0 +1,20 @@
+## Now
+
+- [ ] Add Drawer component
+- [ ] Make utility components (e.g., Item) into proper components (i.e., .item)
+- [ ] Split CSS into components
+
+## Next
+
+- [ ] Make Command load dynamic items (e.g. search results from remote endpoint)
+- [ ] Make Combobox load dynamic items (e.g. search results from remote endpoint)
+- [ ] Add Toggle component
+- [ ] Add Carousel component
+- [ ] Add Sheet component
+- [ ] Add Separator component
+- [ ] Adding Menubar component
+
+## Later
+
+- [ ] Add Calendar component (https://flatpickr.js.org/)
+- [ ] Finish Chart component (https://www.chartjs.org/)
@@ -50,7 +50,7 @@
        @apply border-t pt-3 mt-3 first:mt-0;
      }
      dd {
-        @apply mt-2;
+        @apply mt-2 space-y-2;
      }
      dl {
        @apply mt-4 border-b-0 pb-0 pl-8 my-0;
@@ -583,6 +583,9 @@
  .w-\[200px\] {
    width: 200px;
  }
+  .w-\[220px\] {
+    width: 220px;
+  }
  .w-\[271px\] {
    width: 271px;
  }
@@ -4241,6 +4244,24 @@
  *:not(select).select {
    position: relative;
    display: inline-flex;
+    & > button {
+      justify-content: space-between;
+      --tw-font-weight: var(--font-weight-normal);
+      font-weight: var(--font-weight-normal);
+      &[aria-invalid='true'] {
+        border-color: var(--color-destructive);
+        --tw-ring-color: var(--color-destructive);
+        @supports (color: color-mix(in lab, red, red)) {
+          --tw-ring-color: color-mix(in oklab, var(--color-destructive) 20%, transparent);
+        }
+        &:is(.dark *) {
+          --tw-ring-color: var(--color-destructive);
+          @supports (color: color-mix(in lab, red, red)) {
+            --tw-ring-color: color-mix(in oklab, var(--color-destructive) 40%, transparent);
+          }
+        }
+      }
+    }
    [data-popover] {
      padding: calc(var(--spacing) * 1);
      [role='option'] {
@@ -5252,12 +5273,12 @@
      text-overflow: ellipsis;
      white-space: nowrap;
      border-radius: var(--radius-md);
-      background-color: var(--color-primary);
+      background-color: var(--color-foreground);
      padding-inline: calc(var(--spacing) * 3);
      padding-block: calc(var(--spacing) * 1.5);
      font-size: var(--text-xs);
      line-height: var(--tw-leading, var(--text-xs--line-height));
-      color: var(--color-primary-foreground);
+      color: var(--color-background);
      opacity: 0%;
      transition-property: all;
      transition-timing-function: var(--tw-ease, var(--default-transition-timing-function));
@@ -5532,6 +5553,11 @@
      }
      dd {
        margin-top: calc(var(--spacing) * 2);
+        :where(& > :not(:last-child)) {
+          --tw-space-y-reverse: 0;
+          margin-block-start: calc(calc(var(--spacing) * 2) * var(--tw-space-y-reverse));
+          margin-block-end: calc(calc(var(--spacing) * 2) * calc(1 - var(--tw-space-y-reverse)));
+        }
      }
      dl {
        margin-block: calc(var(--spacing) * 0);
@@ -131,7 +131,7 @@ toc:
    <button type="button" class="btn-icon-outline">{% lucide "plus" %}</button>
  </div>
  <div role="group" class="button-group">
-    <button type="button" class="btn-lg-outline">Small</button>
+    <button type="button" class="btn-lg-outline">Large</button>
    <button type="button" class="btn-lg-outline">Button</button>
    <button type="button" class="btn-lg-outline">Group</button>
    <button type="button" class="btn-lg-icon-outline">{% lucide "plus" %}</button>
@@ -287,4 +287,4 @@ toc:
 </div>
 {% endset %}

-{{ code_preview("button-group-popover", code_popover | prettyHtml) }}
+{{ code_preview("button-group-popover", code_popover | prettyHtml) }}
@@ -32,6 +32,8 @@ toc:
        id: example-disabled
      - label: With icon
        id: example-with-icon
+      - label: Multiple
+        id: example-multiple
 ---

 {% from "macros/code_preview.njk" import code_preview %}
@@ -120,44 +122,62 @@ toc:
 <section class="prose">
  <dl>
    <dt><code class="highlight language-html">&lt;div class="select"&gt;</code></dt>
-    <dd>Wraps around the entire component.
+    <dd>
+      <p>Wraps around the entire component. Can have the following attributes:</p>
+      <ul>
+        <li><code>data-placeholder="{ TEXT }"</code> <span class="badge-secondary">Optional</span>: placeholder text shown when no options are selected (multiselect only).</li>
+      </ul>
      <dl>
-        <dt><code class="highlight language-html">&lt;button type="button" popovertarget="{ POPOVER_ID }"&gt;</code></dt>
+        <dt><code class="highlight language-html">&lt;button type="button"&gt;</code></dt>
        <dd>
-          <p>The trigger to open the popover, can also have the following attributes:</p>
+          <p>The trigger to open the popover. Should have the following attributes:</p>
          <ul>
            <li><code>id="{BUTTON_ID}"</code>: linked to by the <code>aria-labelledby</code> attribute of the listbox.</li>
            <li><code>aria-haspopup="listbox"</code>: indicates that the button opens a listbox.</li>
            <li><code>aria-controls="{ LISTBOX_ID }"</code>: points to the listbox's id.</li>
            <li><code>aria-expanded="false"</code>: tracks the popover's state.</li>
-            <li><code>aria-activedescendant="{ OPTION_ID }"</code>: points to the active option's id.</li>
+            <li><code>aria-activedescendant="{ OPTION_ID }"</code> <span class="badge-secondary">Optional</span>: points to the active option's id.</li>
          </ul>
        </dd>
-        <dt><code class="highlight language-html">&lt;div popover class="popover" id="{ POPOVER_ID }"&gt;</code></dt>
-        <dd>As with the <a href="/components/popover">Popover</a> component, you can set up the side and alignment of the popover using the <code>data-side</code> and <code>data-align</code> attributes.
+        <dt><code class="highlight language-html">&lt;div data-popover aria-hidden="true" id="{ POPOVER_ID }"&gt;</code></dt>
+        <dd>The popover content. You can set up the side and alignment using the <code>data-side</code> and <code>data-align</code> attributes (see <a href="/components/popover">Popover</a> component).
        <dl>
          <dt><code class="highlight language-html">&lt;div role="listbox"&gt;</code></dt>
-          <dd>The listbox containing the options. Should have the following attributes:
+          <dd>
+            <p>The listbox containing the options. Should have the following attributes:</p>
            <ul>
              <li><code>id="{ LISTBOX_ID }"</code>: refered to by the <code>aria-controls</code> attribute of the trigger.</li>
              <li><code>aria-labelledby="{ BUTTON_ID }"</code>: linked to by the button's <code>id</code> attribute.</li>
+              <li><code>aria-multiselectable="true"</code> <span class="badge-secondary">Optional</span>: enables multiple selection mode.</li>
            </ul>
            <dl>
              <dt><code class="highlight language-html">&lt;div role="option" data-value="{ VALUE }"&gt;</code></dt>
-              <dd>Option that can be selected.Should have a unique id if you use the <code>aria-activedescendant</code> attribute on the trigger.</dd>
+              <dd>
+                <p>Option that can be selected. Should have the following attributes:</p>
+                <ul>
+                  <li><code>id="{ OPTION_ID }"</code> <span class="badge-secondary">Optional</span>: unique id for this option (needed if you use <code>aria-activedescendant</code> on the trigger).</li>
+                  <li><code>data-value="{ VALUE }"</code>: the value for this option.</li>
+                  <li><code>data-label="{ LABEL }"</code> <span class="badge-secondary">Optional</span>: the text label to use for this option when selected in multiple mode. If not provided, the option's text content will be used (HTML stripped).</li>
+                  <li><code>aria-selected="true"</code> <span class="badge-secondary">Optional</span>: indicates this option is selected.</li>
+                </ul>
+              </dd>
              <dt><code class="highlight language-html">&lt;hr role="separator"&gt;</code> <span class="badge-secondary">Optional</span></dt>
              <dd>Separator between groups/options.</dd>
              <dt><code class="highlight language-html">&lt;div role="group"&gt;</code> <span class="badge-secondary">Optional</span></dt>
              <dd>Group of options, can have a <code>aria-labelledby</code> attribute to link to a heading.</dd>
-              <dt><code class="highlight language-html">&lt;span role="heading"&gt;</code></dt>
+              <dt><code class="highlight language-html">&lt;span role="heading"&gt;</code> <span class="badge-secondary">Optional</span></dt>
              <dd>Group heading, must have an <code>id</code> attribute if you use the <code>aria-labelledby</code> attribute on the group.</dd>
            </dl>
          </dd>
        </dl>
      </dl>
    </dd>
-    <dt><code class="highlight language-html">&lt;input type="hidden" name="{ NAME }" value="{ VALUE }"&gt;</code> <span class="badge-secondary">Optional</span></dt>
-    <dd>The hidden input that holds the value of the field (if needed).</dd>
+    <dt><code class="highlight language-html">&lt;input type="hidden" name="{ NAME }" value="{ VALUE }"&gt;</code></dt>
+    <dd>
+      <p>The hidden input that holds the selected value.</p>
+      <p>For multiselect: multiple hidden inputs with the same name will be created (one for each selected value). When no options are selected, a single input with an empty value is submitted.</p>
+      <p><strong>Note:</strong> This differs slightly from native <code>&lt;select multiple&gt;</code> behavior, which submits nothing when empty. This allows the component to work without JavaScript for initial rendering while maintaining a simpler architecture.</p>
+    </dd>
  </dl>
 </section>

@@ -170,7 +190,13 @@ toc:
    <dt><code>basecoat:popover</code></dt>
    <dd>When the popover opens, the component dispatches a custom (non-bubbling) <code>basecoat:popover</code> event on <code>document</code>. Other popover components (Combobox, Dropdown Menu, Popover and Select) listen for this to close any open popovers.</dd>
    <dt><code>change</code></dt>
-    <dd>When the selected value changes, the component dispatches a custom (bubbling) <code>change</code> event on itself, with the selected value in <code>event.detail</code> (e.g. <code>{ detail: { value: "something" }}</code>).</dd>
+    <dd>
+      <p>When the selected value changes, the component dispatches a custom (bubbling) <code>change</code> event on itself, with the selected value in <code>event.detail.value</code>:</p>
+      <ul>
+        <li>Single select: <code>{ detail: { value: "something" }}</code> (string)</li>
+        <li>Multiple select: <code>{ detail: { value: ["item1", "item2"] }}</code> (array)</li>
+      </ul>
+    </dd>
  </dl>
 </section>

@@ -178,9 +204,9 @@ toc:

 <section class="prose">
  <dl>
-    <dt><code>selectByValue</code></dt>
+    <dt><code>selectByValue(value)</code></dt>
    <dd>
-      <p>You can call this method on the component after it is initialized to select an option by value (i.e. the option with the matching <code>data-value</code> attribute):</p>
+      <p>Selects an option by value (i.e. the option with the matching <code>data-value</code> attribute). For single-select, this will close the popover. For multiselect, this adds the value to the selection without removing existing selections.</p>

 {% set code_script %}<script>
  const selectComponent = document.querySelector('#my-select');
@@ -190,6 +216,30 @@ toc:
 </script>{% endset %}
 {{ code_block(code_script | prettyHtml, "html") }}
    </dd>
+    <dt><code>selectAll()</code> <span class="badge-secondary">Multiselect only</span></dt>
+    <dd>
+      <p>Selects all available options. Only available when the component is in multiselect mode (<code>aria-multiselectable="true"</code>).</p>
+
+{% set code_script_all %}<script>
+  const selectComponent = document.querySelector('#my-multiselect');
+  selectComponent.addEventListener('basecoat:initialized', () => {
+    selectComponent.selectAll();
+  });
+</script>{% endset %}
+{{ code_block(code_script_all | prettyHtml, "html") }}
+    </dd>
+    <dt><code>selectNone()</code> <span class="badge-secondary">Multiselect only</span></dt>
+    <dd>
+      <p>Deselects all options. Only available when the component is in multiselect mode (<code>aria-multiselectable="true"</code>).</p>
+
+{% set code_script_none %}<script>
+  const selectComponent = document.querySelector('#my-multiselect');
+  selectComponent.addEventListener('basecoat:initialized', () => {
+    selectComponent.selectNone();
+  });
+</script>{% endset %}
+{{ code_block(code_script_none | prettyHtml, "html") }}
+    </dd>
  </dl>
 </section>

@@ -204,11 +254,11 @@ toc:
    Use Nunjucks or Jinja macros
    {% lucide "arrow-right" %}
  </a>
-  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/jinja/dialog.html.jinja" target="_blank">
+  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/jinja/select.html.jinja" target="_blank">
    Jinja macro
    {% lucide "arrow-right" %}
  </a>
-  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/nunjucks/dialog.njk" target="_blank">
+  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/nunjucks/select.njk" target="_blank">
    Nunjucks macro
    {% lucide "arrow-right" %}
  </a>
@@ -259,11 +309,29 @@ toc:

 {{ code_preview("select-disabled", code | prettyHtml) }}

+<h3 id="example-invalid-state"><a href="#example-invalid-state">Invalid State</a></h3>
+
+{% set code %}
+{{ select(
+  trigger_attrs={"aria-invalid": "true"},
+  items=[
+    { value: "", label: "Select a role" },
+    { value: "admin", label: "Admin" },
+    { value: "editor", label: "Editor" },
+    { value: "viewer", label: "Viewer" },
+    { value: "guest", label: "Guest" }
+  ]
+) }}
+{% endset %}
+
+{{ code_preview("select-disabled", code | prettyHtml) }}
+
 <h3 id="example-with-icon"><a href="#example-with-icon">With icon</a></h3>

 {% set code %}
 {% call select(
  id="select-with-icons",
+  placeholder="Select a chart...",
  trigger_attrs={'class': 'w-[180px]'}
 ) %}
 <div type="button" role="option" data-value="bar">
@@ -287,4 +355,48 @@ toc:
 {% endcall %}
 {% endset %}

-{{ code_preview("select-scrollable", code | prettyHtml) }}
+{{ code_preview("select-with-icons", code | prettyHtml) }}
+
+<h3 id="example-multiple"><a href="#example-multiple">Multiple</a></h3>
+
+<section class="prose">
+  <p>Enable multiple selection by setting <code>multiple=true</code>. The selected options are displayed as a comma-separated list in the trigger button. Use <code>data-label</code> to specify clean text labels for options that contain HTML (like icons), otherwise the text content will be extracted automatically.</p>
+</section>
+
+{% set code %}
+{% call select(
+  id="select-multiple",
+  name="chart-types",
+  multiple=true,
+  placeholder="Select chart types...",
+  selected=["bar", "line"],
+  trigger_attrs={"class": "w-[220px]"}
+) %}
+<div role="option" data-value="bar" data-label="Bar">
+  <span class="flex items-center gap-2">
+    {% lucide "chart-bar", {"class": "text-muted-foreground"} %}
+    Bar
+  </span>
+</div>
+<div role="option" data-value="line" data-label="Line">
+  <span class="flex items-center gap-2">
+    {% lucide "chart-line", {"class": "text-muted-foreground"} %}
+    Line
+  </span>
+</div>
+<div role="option" data-value="pie" data-label="Pie">
+  <span class="flex items-center gap-2">
+    {% lucide "chart-pie", {"class": "text-muted-foreground"} %}
+    Pie
+  </span>
+</div>
+<div role="option" data-value="area" data-label="Area">
+  <span class="flex items-center gap-2">
+    {% lucide "chart-area", {"class": "text-muted-foreground"} %}
+    Area
+  </span>
+</div>
+{% endcall %}
+{% endset %}
+
+{{ code_preview("select-multiple", code | prettyHtml) }}
@@ -144,7 +144,7 @@ import 'basecoat-css/tabs';{% endraw %}{% endset %}
 <h2 id="install-js"><a href="#install-js">Components with JavaScript</a></h2>

 <div class="prose">
-  <p><b>A handful of components require JavaScript code to work.</b>, specifically <a href="/components/dropdown-menu">Dropdown Menu</a>, <a href="/components/popover">Popover</a>, <a href="/components/select">Select</a>, <a href="/components/sidebar">Sidebar</a>, <a href="/components/tabs">Tabs</a> and <a href="/components/toast">Toast</a></p>
+  <p><b>A handful of components require JavaScript code to work</b>, specifically <a href="/components/dropdown-menu">Dropdown Menu</a>, <a href="/components/popover">Popover</a>, <a href="/components/select">Select</a>, <a href="/components/sidebar">Sidebar</a>, <a href="/components/tabs">Tabs</a> and <a href="/components/toast">Toast</a></p>

  <p>If a component requires JavaScript, the documentation page will provide instructions. There are 2 options to add the JavaScript code to your project:</p>
    
@@ -1,6 +1,6 @@
 {
  "name": "basecoat",
-  "version": "0.3.9",
+  "version": "0.3.10-beta.1",
  "description": "shadcn/ui for the rest of us",
  "author": "hunvreus",
  "type": "module",
@@ -1,6 +1,6 @@
 {
  "name": "basecoat-cli",
-  "version": "0.3.9",
+  "version": "0.3.10-beta.1",
  "description": "Add Basecoat components to your project",
  "author": "hunvreus",
  "license": "MIT",
@@ -1,6 +1,6 @@
 {
  "name": "basecoat-css",
-  "version": "0.3.9",
+  "version": "0.3.10-beta.1",
  "description": "Tailwind CSS for Basecoat components",
  "author": {
    "name": "hunvreus",
@@ -941,6 +941,14 @@
  }
  *:not(select).select {
    @apply relative inline-flex;
+    
+    & > button {
+      @apply justify-between font-normal;
+
+      &[aria-invalid='true'] {
+        @apply ring-destructive/20 dark:ring-destructive/40 border-destructive;
+      }
+    }

    [data-popover] {
      @apply p-1;
@@ -1250,7 +1258,7 @@
    @apply relative;

    &:before {
-      @apply absolute content-[attr(data-tooltip)] bg-primary text-primary-foreground z-[60] truncate max-w-xs w-fit rounded-md px-3 py-1.5 text-xs invisible opacity-0 scale-95 transition-all pointer-events-none;
+      @apply absolute content-[attr(data-tooltip)] bg-foreground text-background z-[60] truncate max-w-xs w-fit rounded-md px-3 py-1.5 text-xs invisible opacity-0 scale-95 transition-all pointer-events-none;
    }
    &:hover:before {
      @apply visible opacity-100 scale-100;
@@ -2,8 +2,10 @@
  Renders a select or combobox component.

  @param id {string} [optional] - Unique identifier for the select component.
-  @param selected {string} [optional] - The initially selected value.
+  @param selected {string|array} [optional] - The initially selected value(s).
  @param name {string} [optional] - The name attribute for the hidden input storing the selected value.
+  @param multiple {boolean} [optional] [default=false] - Enables multiple selection mode.
+  @param placeholder {string} [optional] - Placeholder text shown when no options are selected (multiple mode only).
  @param main_attrs {object} [optional] - Additional HTML attributes for the main container div.
  @param trigger_attrs {object} [optional] - Additional HTML attributes for the trigger button.
  @param popover_attrs {object} [optional] - Additional HTML attributes for the popover content div.
@@ -17,6 +19,8 @@
  selected=None,
  name=None,
  items=[],
+  multiple=false,
+  placeholder=None,
  main_attrs={},
  trigger_attrs={},
  popover_attrs={},
@@ -27,8 +31,9 @@
 ) %}
 {% set id = id or ("select-" + (range(100000, 999999) | random | string)) %}

+{% set selectedArray = ((selected if (selected is iterable and selected is not string) else [selected]) if selected else []) %}
 {% set first_option = namespace(item=None) %}
-{% set selected_option = namespace(item=None) %}
+{% set selected_options = namespace(items=[]) %}

 {% if items %}
  {% for item in items %}
@@ -37,33 +42,41 @@
        {% if not first_option.item %}
          {% set first_option.item = sub_item %}
        {% endif %}
-        {% if selected and sub_item.value == selected and not selected_option.item %}
-          {% set selected_option.item = sub_item %}
+        {% if sub_item.value in selectedArray %}
+          {% set selected_options.items = selected_options.items + [sub_item] %}
        {% endif %}
      {% endfor %}
    {% else %}
      {% if not first_option.item %}
        {% set first_option.item = item %}
      {% endif %}
-      {% if selected and item.value == selected and not selected_option.item %}
-        {% set selected_option.item = item %}
+      {% if item.value in selectedArray %}
+        {% set selected_options.items = selected_options.items + [item] %}
      {% endif %}
    {% endif %}
  {% endfor %}
 {% endif %}

-{% set default_option = selected_option.item or first_option.item or None %}
+{% set default_option = (selected_options.items[0] if selected_options.items else first_option.item) %}
+{% set labels = [] %}
+{% if multiple and selected_options.items %}
+  {% for opt in selected_options.items %}
+    {% set labels = labels + [opt.label] %}
+  {% endfor %}
+{% endif %}
+{% set default_label = (', '.join(labels) if (multiple and selected_options.items) else ((placeholder or '') if (multiple and not selected_options.items) else (default_option.label if default_option else ''))) %}

 <div
  id="{{ id }}"
  class="select {{ main_attrs.class }}"
+  {% if multiple and placeholder %}data-placeholder="{{ placeholder }}"{% endif %}
  {% for key, value in main_attrs.items() %}
    {% if key != 'class' %}{{ key }}="{{ value }}"{% endif %}
  {% endfor %}
 >
  <button
    type="button"
-    class="btn-outline justify-between font-normal {{ trigger_attrs.class }}"
+    class="btn-outline {{ trigger_attrs.class }}"
    id="{{ id }}-trigger"
    aria-haspopup="listbox"
    aria-expanded="false"
@@ -72,7 +85,7 @@
      {% if key != 'class' %}{{ key }}="{{ value }}"{% endif %}
    {% endfor %}
  >
-    <span class="truncate">{{ default_option.label }}</span>
+    <span class="truncate">{{ default_label }}</span>
    {% if is_combobox %}
      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevrons-up-down-icon lucide-chevrons-up-down text-muted-foreground opacity-50 shrink-0"><path d="m7 15 5 5 5-5"/><path d="m7 9 5-5 5 5"/></svg>
    {% else %}
@@ -110,25 +123,40 @@
      id="{{ id }}-listbox"
      aria-orientation="vertical"
      aria-labelledby="{{ id }}-trigger"
+      {% if multiple %}aria-multiselectable="true"{% endif %}
      {% for key, value in listbox_attrs.items() %}
        {{ key }}="{{ value }}"
      {% endfor %}
    >
      {% if items %}
-        {{ render_select_items(items, default_option.value, id ~ "-items" if id else "items") }}
+        {{ render_select_items(items, selectedArray, id ~ "-items" if id else "items") }}
      {% else %}
        {{ caller() if caller }}
      {% endif %}
    </div>
  </div>
-  <input
-    type="hidden"
-    name="{{ name or id ~ '-value' }}"
-    value="{{ (default_option.value if default_option) or '' }}"
-    {% for key, value in input_attrs.items() %}
-      {% if key != 'name' and key != 'value' %}{{ key }}="{{ value }}"{% endif %}
+  {% if multiple and selectedArray %}
+    {% for val in selectedArray %}
+      <input
+        type="hidden"
+        name="{{ name or id ~ '-value' }}"
+        value="{{ val }}"
+        {% if loop.index0 > 0 %}id="{{ id }}-value-{{ loop.index0 }}"{% endif %}
+        {% for key, value in input_attrs.items() %}
+          {% if key != 'name' and key != 'value' %}{{ key }}="{{ value }}"{% endif %}
+        {% endfor %}
+      >
    {% endfor %}
-  >
+  {% else %}
+    <input
+      type="hidden"
+      name="{{ name or id ~ '-value' }}"
+      value="{{ (default_option.value if default_option) or '' }}"
+      {% for key, value in input_attrs.items() %}
+        {% if key != 'name' and key != 'value' %}{{ key }}="{{ value }}"{% endif %}
+      {% endfor %}
+    >
+  {% endif %}
 </div>
 {% endmacro %}

@@ -138,7 +166,7 @@
  @param items {array} - The array of items to render.
  @param parent_id_prefix {string} [optional] - The prefix for the item id.
 #}
-{% macro render_select_items(items, selected, parent_id_prefix="items") %}
+{% macro render_select_items(items, selectedArray, parent_id_prefix="items") %}
  {% for item in items %}
    {% set item_id = parent_id_prefix ~ "-" ~ loop.index %}
    {% if item.type == "group" %}
@@ -153,7 +181,7 @@
        {% endif %}
      >
        <div role="heading" id="{{ group_label_id }}">{{ item.label }}</div>
-        {{ render_select_items(item['items'], selected, item_id) if item['items'] }}
+        {{ render_select_items(item['items'], selectedArray, item_id) if item['items'] }}
      </div>
    {% elif item.type == "separator" %}
      <hr role="separator" />
@@ -162,7 +190,7 @@
        id="{{ item_id }}"
        role="option"
        data-value="{{ item.value }}"
-        {% if selected == item.value %}aria-selected="true"{% endif %}
+        {% if item.value in selectedArray %}aria-selected="true"{% endif %}
        {% if item.attrs %}
          {% for key, value in item.attrs.items() %}
            {{ key }}="{{ value }}"
@@ -3,23 +3,31 @@
    const trigger = selectComponent.querySelector(':scope > button');
    const selectedLabel = trigger.querySelector(':scope > span');
    const popover = selectComponent.querySelector(':scope > [data-popover]');
-    const listbox = popover.querySelector('[role="listbox"]');
+    const listbox = popover ? popover.querySelector('[role="listbox"]') : null;
    const input = selectComponent.querySelector(':scope > input[type="hidden"]');
    const filter = selectComponent.querySelector('header input[type="text"]');
+
    if (!trigger || !popover || !listbox || !input) {
      const missing = [];
      if (!trigger) missing.push('trigger');
      if (!popover) missing.push('popover');
      if (!listbox) missing.push('listbox');
-      if (!input)   missing.push('input');
+      if (!input) missing.push('input');
      console.error(`Select component initialisation failed. Missing element(s): ${missing.join(', ')}`, selectComponent);
      return;
    }
-    
+
    const allOptions = Array.from(listbox.querySelectorAll('[role="option"]'));
    const options = allOptions.filter(opt => opt.getAttribute('aria-disabled') !== 'true');
    let visibleOptions = [...options];
    let activeIndex = -1;
+    const isMultiple = listbox.getAttribute('aria-multiselectable') === 'true';
+    let selectedValues = isMultiple ? new Set() : null;
+    let placeholder = null;
+
+    if (isMultiple) {
+      placeholder = selectComponent.dataset.placeholder || '';
+    }

    const setActiveOption = (index) => {
      if (activeIndex > -1 && options[activeIndex]) {
@@ -46,23 +54,92 @@
      return parseFloat(style.transitionDuration) > 0 || parseFloat(style.transitionDelay) > 0;
    };

-    const updateValue = (option, triggerEvent = true) => {
-      if (option) {
-        selectedLabel.innerHTML = option.innerHTML;
-        input.value = option.dataset.value;
-        listbox.querySelector('[role="option"][aria-selected="true"]')?.removeAttribute('aria-selected');
-        option.setAttribute('aria-selected', 'true');
-        
-        if (triggerEvent) {
-          const event = new CustomEvent('change', {
-            detail: { value: option.dataset.value },
-            bubbles: true
-          });
-          selectComponent.dispatchEvent(event);
+    const syncMultipleInputs = () => {
+      if (!isMultiple) return;
+      const values = Array.from(selectedValues);
+      const inputs = Array.from(selectComponent.querySelectorAll(':scope > input[type="hidden"]'));
+      inputs.slice(1).forEach(inp => inp.remove());
+
+      if (values.length === 0) {
+        input.value = '';
+      } else {
+        input.value = values[0];
+        let insertAfter = input;
+        for (let i = 1; i < values.length; i++) {
+          const clone = input.cloneNode(true);
+          clone.removeAttribute('id');
+          clone.value = values[i];
+          insertAfter.after(clone);
+          insertAfter = clone;
        }
      }
    };

+    const updateMultipleLabel = () => {
+      if (!isMultiple) return;
+      const selected = options.filter(opt => selectedValues.has(opt.dataset.value));
+      if (selected.length === 0) {
+        selectedLabel.textContent = placeholder;
+        selectedLabel.classList.add('text-muted-foreground');
+      } else {
+        selectedLabel.textContent = selected.map(opt => opt.dataset.label || opt.textContent.trim()).join(', ');
+        selectedLabel.classList.remove('text-muted-foreground');
+      }
+    };
+
+    const updateValue = (optionOrOptions, triggerEvent = true) => {
+      let value;
+
+      if (isMultiple) {
+        const opts = Array.isArray(optionOrOptions) ? optionOrOptions : [];
+        selectedValues = new Set(opts.map(opt => opt.dataset.value));
+        options.forEach(opt => {
+          if (selectedValues.has(opt.dataset.value)) {
+            opt.setAttribute('aria-selected', 'true');
+          } else {
+            opt.removeAttribute('aria-selected');
+          }
+        });
+        updateMultipleLabel();
+        syncMultipleInputs();
+        value = Array.from(selectedValues);
+      } else {
+        const option = optionOrOptions;
+        if (!option) return;
+        selectedLabel.innerHTML = option.innerHTML;
+        input.value = option.dataset.value;
+        options.forEach(opt => {
+          if (opt === option) {
+            opt.setAttribute('aria-selected', 'true');
+          } else {
+            opt.removeAttribute('aria-selected');
+          }
+        });
+        value = option.dataset.value;
+      }
+
+      if (triggerEvent) {
+        selectComponent.dispatchEvent(new CustomEvent('change', {
+          detail: { value },
+          bubbles: true
+        }));
+      }
+    };
+
+    const toggleMultipleValue = (value, triggerEvent = true) => {
+      if (!isMultiple || value == null) return;
+
+      const newValues = new Set(selectedValues);
+      if (newValues.has(value)) {
+        newValues.delete(value);
+      } else {
+        newValues.add(value);
+      }
+
+      const selectedOptions = options.filter(opt => newValues.has(opt.dataset.value));
+      updateValue(selectedOptions, triggerEvent);
+    };
+
    const closePopover = (focusOnTrigger = true) => {
      if (popover.getAttribute('aria-hidden') === 'true') return;
      
@@ -101,7 +178,27 @@

    const selectByValue = (value) => {
      const option = options.find(opt => opt.dataset.value === value);
-      selectOption(option);
+      if (isMultiple) {
+        if (value != null && selectedValues.has(value)) return;
+        if (option && value != null) {
+          const newValues = new Set(selectedValues);
+          newValues.add(value);
+          const selectedOptions = options.filter(opt => newValues.has(opt.dataset.value));
+          updateValue(selectedOptions);
+        }
+      } else {
+        selectOption(option);
+      }
+    };
+
+    const selectAll = () => {
+      if (!isMultiple) return;
+      updateValue(options.filter(opt => opt.dataset.value != null));
+    };
+
+    const selectNone = () => {
+      if (!isMultiple) return;
+      updateValue([]);
    };

    if (filter) {
@@ -137,13 +234,32 @@
      filter.addEventListener('input', filterOptions);
    }

-    let initialOption = options.find(opt => opt.dataset.value === input.value);
-    
-    if (!initialOption) {
-      initialOption = options.find(opt => opt.dataset.value !== undefined) ?? options[0];
-    }
+    if (isMultiple) {
+      const validValues = new Set(options.map(opt => opt.dataset.value).filter(v => v != null));
+      const inputs = Array.from(selectComponent.querySelectorAll(':scope > input[type="hidden"]'));
+      const initialValues = inputs
+        .map(inp => inp.value)
+        .filter(v => v != null && validValues.has(v));

-    updateValue(initialOption, false);
+      let initialOptions;
+      if (initialValues.length > 0) {
+        initialOptions = options.filter(opt => initialValues.includes(opt.dataset.value));
+      } else {
+        initialOptions = options.filter(opt => opt.getAttribute('aria-selected') === 'true');
+      }
+
+      updateValue(initialOptions, false);
+    } else {
+      let initialOption = options.find(opt => opt.dataset.value === input.value);
+
+      if (!initialOption) {
+        initialOption = options.find(opt => opt.dataset.value !== undefined) ?? options[0];
+      }
+
+      if (initialOption) {
+        updateValue(initialOption, false);
+      }
+    }

    const handleKeyNavigation = (event) => {
      const isPopoverOpen = popover.getAttribute('aria-hidden') === 'false';
@@ -169,7 +285,11 @@
      
      if (event.key === 'Enter') {
        if (activeIndex > -1) {
-          selectOption(options[activeIndex]);
+          if (isMultiple) {
+            toggleMultipleValue(options[activeIndex].dataset.value);
+          } else {
+            selectOption(options[activeIndex]);
+          }
        }
        return;
      }
@@ -268,7 +388,17 @@
    listbox.addEventListener('click', (event) => {
      const clickedOption = event.target.closest('[role="option"]');
      if (clickedOption) {
-        selectOption(clickedOption);
+        if (isMultiple) {
+          toggleMultipleValue(clickedOption.dataset.value);
+          setActiveOption(options.indexOf(clickedOption));
+          if (filter) {
+            filter.focus();
+          } else {
+            trigger.focus();
+          }
+        } else {
+          selectOption(clickedOption);
+        }
      }
    });

@@ -285,8 +415,12 @@
    });

    popover.setAttribute('aria-hidden', 'true');
-    
+
    selectComponent.selectByValue = selectByValue;
+    if (isMultiple) {
+      selectComponent.selectAll = selectAll;
+      selectComponent.selectNone = selectNone;
+    }
    selectComponent.dataset.selectInitialized = true;
    selectComponent.dispatchEvent(new CustomEvent('basecoat:initialized'));
  };
@@ -2,8 +2,10 @@
  Renders a select or combobox component.

  @param id {string} [optional] - Unique identifier for the select component.
-  @param selected {string} [optional] - The initially selected value.
+  @param selected {string|array} [optional] - The initially selected value(s).
  @param name {string} [optional] - The name attribute for the hidden input storing the selected value.
+  @param multiple {boolean} [optional] [default=false] - Enables multiple selection mode.
+  @param placeholder {string} [optional] - Placeholder text shown when no options are selected (multiple mode only).
  @param main_attrs {object} [optional] - Additional HTML attributes for the main container div.
  @param trigger_attrs {object} [optional] - Additional HTML attributes for the trigger button.
  @param popover_attrs {object} [optional] - Additional HTML attributes for the popover content div.
@@ -17,6 +19,8 @@
  selected=None,
  name=None,
  items=None,
+  multiple=false,
+  placeholder=None,
  main_attrs={},
  trigger_attrs={},
  popover_attrs={},
@@ -27,8 +31,9 @@
 ) %}
 {% set id = id or ("select-" + (range(100000, 999999) | random | string)) %}

+{% set selectedArray = ((selected if (selected is iterable and selected is not string) else [selected]) if selected else []) %}
 {% set first_option = [] %}
-{% set selected_option = [] %}
+{% set selected_options = [] %}

 {% if items %}
  {% for item in items %}
@@ -37,33 +42,41 @@
        {% if not first_option[0] %}
          {% set first_option = (first_option.push(sub_item), first_option) %}
        {% endif %}
-        {% if selected and sub_item.value == selected and not selected_option[0] %}
-          {% set selected_option = (selected_option.push(sub_item), selected_option) %}
+        {% if sub_item.value in selectedArray %}
+          {% set selected_options = (selected_options.push(sub_item), selected_options) %}
        {% endif %}
      {% endfor %}
    {% else %}
      {% if not first_option[0] %}
        {% set first_option = (first_option.push(item), first_option) %}
      {% endif %}
-      {% if selected and item.value == selected and not selected_option[0] %}
-        {% set selected_option = (selected_option.push(item), selected_option) %}
+      {% if item.value in selectedArray %}
+        {% set selected_options = (selected_options.push(item), selected_options) %}
      {% endif %}
    {% endif %}
  {% endfor %}
 {% endif %}

-{% set default_option = selected_option[0] or first_option[0] or None %}
+{% set default_option = (selected_options[0] if selected_options[0] else (first_option[0] if first_option[0] else None)) %}
+{% set labels = [] %}
+{% if multiple and selected_options %}
+  {% for opt in selected_options %}
+    {% set labels = (labels.push(opt.label), labels) %}
+  {% endfor %}
+{% endif %}
+{% set default_label = (labels | join(', ') if (multiple and selected_options) else ((placeholder or '') if (multiple and not selected_options) else (default_option.label if default_option else ''))) %}

 <div
  id="{{ id }}"
  class="select {{ main_attrs.class }}"
+  {% if multiple and placeholder %}data-placeholder="{{ placeholder }}"{% endif %}
  {% for key, value in main_attrs %}
    {% if key != 'class' %}{{ key }}="{{ value }}"{% endif %}
  {% endfor %}
 >
  <button
    type="button"
-    class="btn-outline justify-between font-normal {{ trigger_attrs.class }}"
+    class="btn-outline {{ trigger_attrs.class }}"
    id="{{ id }}-trigger"
    aria-haspopup="listbox"
    aria-expanded="false"
@@ -72,7 +85,7 @@
      {% if key != 'class' %}{{ key }}="{{ value }}"{% endif %}
    {% endfor %}
  >
-    <span class="truncate">{{ default_option.label }}</span>
+    <span class="truncate">{{ default_label }}</span>
    {% if is_combobox %}
      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevrons-up-down-icon lucide-chevrons-up-down text-muted-foreground opacity-50 shrink-0"><path d="m7 15 5 5 5-5"/><path d="m7 9 5-5 5 5"/></svg>
    {% else %}
@@ -110,25 +123,40 @@
      id="{{ id }}-listbox"
      aria-orientation="vertical"
      aria-labelledby="{{ id }}-trigger"
+      {% if multiple %}aria-multiselectable="true"{% endif %}
      {% for key, value in listbox_attrs %}
        {{ key }}="{{ value }}"
      {% endfor %}
    >
      {% if items and items.length > 0 %}
-        {{ render_select_items(items, default_option.value, id ~ "-items" if id else "items") }}
+        {{ render_select_items(items, selectedArray, id ~ "-items" if id else "items") }}
      {% else %}
        {{ caller() if caller }}
      {% endif %}
    </div>
  </div>
-  <input
-    type="hidden"
-    name="{{ name or id ~ '-value' }}"
-    value="{{ (default_option.value if default_option) or '' }}"
-    {% for key, value in input_attrs %}
-      {% if key != 'name' and key != 'value' %}{{ key }}="{{ value }}"{% endif %}
+  {% if multiple and selectedArray %}
+    {% for val in selectedArray %}
+      <input
+        type="hidden"
+        name="{{ name or id ~ '-value' }}"
+        value="{{ val }}"
+        {% if loop.index0 > 0 %}id="{{ id }}-value-{{ loop.index0 }}"{% endif %}
+        {% for key, value in input_attrs %}
+          {% if key != 'name' and key != 'value' %}{{ key }}="{{ value }}"{% endif %}
+        {% endfor %}
+      >
    {% endfor %}
-  >
+  {% else %}
+    <input
+      type="hidden"
+      name="{{ name or id ~ '-value' }}"
+      value="{{ (default_option.value if default_option) or '' }}"
+      {% for key, value in input_attrs %}
+        {% if key != 'name' and key != 'value' %}{{ key }}="{{ value }}"{% endif %}
+      {% endfor %}
+    >
+  {% endif %}
 </div>
 {% endmacro %}

@@ -138,7 +166,7 @@
  @param items {array} - The array of items to render.
  @param parent_id_prefix {string} [optional] - The prefix for the item id.
 #}
-{% macro render_select_items(items, selected, parent_id_prefix="items") %}
+{% macro render_select_items(items, selectedArray, parent_id_prefix="items") %}
  {% for item in items %}
    {% set item_id = parent_id_prefix ~ "-" ~ loop.index %}
    {% if item.type == "group" %}
@@ -153,7 +181,7 @@
        {% endif %}
      >
        <div role="heading" id="{{ group_label_id }}">{{ item.label }}</div>
-        {{ render_select_items(item.items, selected, item_id) if item.items }}
+        {{ render_select_items(item.items, selectedArray, item_id) if item.items }}
      </div>
    {% elif item.type == "separator" %}
      <hr role="separator" />
@@ -162,7 +190,7 @@
        id="{{ item_id }}"
        role="option"
        data-value="{{ item.value }}"
-        {% if selected == item.value %}aria-selected="true"{% endif %}
+        {% if item.value in selectedArray %}aria-selected="true"{% endif %}
        {% if item.attrs %}
          {% for key, value in item.attrs %}
            {{ key }}="{{ value }}"
Author	SHA1	Message	Date
Ronan Berder	3ec06205a0	Preparing 0.3.10-beta.1	2026-01-04 21:22:53 +08:00
Ronan Berder	06e7c1ec84	Refined multi-select	2026-01-04 19:21:07 +08:00
Ronan Berder	09f868d474	Stable multi-select implementation	2026-01-04 14:39:32 +08:00
Ronan Berder	b9274702d3	Fixing text color in tooltip (see #97 )	2026-01-03 14:24:08 +08:00
Ronan Berder	83c09c1197	Merge branch 'development' of github.com:hunvreus/basecoat into development	2026-01-03 14:21:35 +08:00
Ronan Berder	36bca0c6a7	Merge pull request #97 from PhilipdeRijk/fix/bg-tooltip fix: change tooltip bg color to bg-foreground	2026-01-03 14:20:18 +08:00
Ronan Berder	167b98e573	Merge pull request #126 from tainguyenphat74/main Correct typo	2025-12-30 18:41:15 +08:00
Ronan Berder	4035870578	Merge pull request #125 from wangbinyq/patch-1 fix links for select.njk documentation	2025-12-30 17:13:29 +08:00
Ronan Berder	dea0602b03	Merge pull request #128 from hrbonz/wip/btn_groups_fix_typo docs: fix small word mistake in button group	2025-12-30 17:12:55 +08:00
Stefan 'hr' Berder	19941561d3	docs: fix small word mistake in button group The large button example was using "Small" "button" "group" list of words. It makes more sense to use "Large" as the first word to stay consistent with the other example.	2025-12-30 14:46:35 +07:00
tainguyenphat74	f708994df9	Correct typo	2025-12-28 00:16:38 +07:00
wangb	6fcbb31e30	Fix code preview rendering in select.njk	2025-12-24 15:07:51 +08:00
wangb	0dfc5e061c	fix links for select.njk documentation	2025-12-24 15:05:06 +08:00
PhilipdeRijk	530224c587	fix: change tooltip bg color to bg-foreground	2025-09-26 11:53:09 +02:00