> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplifi.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Select

A scrollable checkbox list that replaces the native `<select multiple>` element. Supports live search filtering, a sticky footer with a running selected count and a "Select all" shortcut, and a dynamic exclude class for programmatic filtering.

***

## Preview

<Frame>
  <img src="https://mintcdn.com/simplifi/c7Rp9XRwuMnkuyeI/images/2026-07-29_11-42-50.jpg?fit=max&auto=format&n=c7Rp9XRwuMnkuyeI&q=85&s=1bbbcb8032e52051cf0774fa03ebfe07" alt="2026 07 29 11 42 50" width="303" height="205" data-path="images/2026-07-29_11-42-50.jpg" />
</Frame>

***

## HTML Structure & JS

<CodeGroup>
  ```html html theme={null}
  <div class="picker" name="ID_FieldName" id="ID_FieldName" style="max-height:200px; overflow-y:auto; flex:1;">

    <!-- Sticky search bar — always the first child -->
    <div class="picker-search">
      <i class="fi fi-rr-search"></i>
      <input type="text" placeholder="Search items..." oninput="filterPicker(this)" />
    </div>

    <!-- One .picker-item per option — add class="checked" for pre-selected items -->
    <div class="picker-item" value="abc123" id="abc123" onclick="togglePick(this)">
      <input name="ID_FieldName" type="checkbox" class="standard-checkbox" value="abc123">
      <span class="pi-name">Option Label</span>
    </div>

    <div class="picker-item checked" value="def456" id="def456" onclick="togglePick(this)">
      <input name="ID_FieldName" type="checkbox" class="standard-checkbox" value="def456" checked>
      <span class="pi-name">Pre-selected Option</span>
    </div>

    <!-- Sticky footer — always the last child -->
    <div class="picker-footer">
      <span class="pickerCount">0 selected</span>
      <a onclick="selectAllPicker(this)">Select all</a>
    </div>

  </div>
  ```

  ```javascript js theme={null}
  //On page load, sync the footer count badge with any pre-checked items
  $(document).ready(function() {
      updatePickerCountOnLoad();
  });
  ```
</CodeGroup>

<Danger>
  `updatePickerCountOnLoad()`must be called in the `$(document).ready` block of every method that renders a picker. Without it, the footer will always display "0 selected" on load even when items are pre-checked.
</Danger>

***

## Search

The `.picker-search` bar is sticky and filters items in real time as the user types. It calls the shared platform function `filterPicker(this)` on every keystroke — no additional setup is required.

The search input has no `name` attribute and is excluded from form serialisation automatically.

***

## Select All

The `.picker-footer` contains a "Select all" link that calls `selectAllPicker(this)`. This selects every visible item in the picker (i.e. items not hidden by search or the `.picker-filterout` class). The footer count updates immediately.

***

## Dynamic Filtering

Items can be hidden programmatically — independently of the search bar — by adding the `.picker-filterout` class. This is used when the visible set of options needs to change based on another selection on the page (e.g. hiding rooms that are not relevant to the currently selected roles).

```css theme={null}
.picker-filterout { display: none !important; }
```

Items with `.picker-filterout` are excluded from "Select all" and do not count toward the footer badge.

<Note>
  `.picker-filterout` must be used instead of setting `display:none` inline so that the platform's filter functions can detect and skip these items correctly.
</Note>

***

## CSS Classes

These classes are defined in the platform's shared stylesheet and must be present on any page that renders this component.

| Class                  | Element | Purpose                                                                                  |
| :--------------------- | :------ | :--------------------------------------------------------------------------------------- |
| `.picker`              | `div`   | Outer container — applies the border, background, and scroll context for the list        |
| `.picker-search`       | `div`   | Sticky search bar at the top of the picker — stays in view while the list scrolls        |
| `.picker-item`         | `div`   | A single selectable row containing a checkbox and label                                  |
| `.picker-item.checked` | `div`   | Applied to a row when its checkbox is selected — green background + label colour         |
| `.picker-footer`       | `div`   | Sticky footer bar at the bottom — contains the selected count and "Select all" link      |
| `.pi-name`             | `span`  | The visible label text inside a `.picker-item`                                           |
| `.standard-checkbox`   | `input` | Shared checkbox style — green accent colour, fixed 14 × 14 px size                       |
| `.picker-filterout`    | `div`   | Hides an item from the list and excludes it from "Select all" — applied programmatically |

<Note>
  The `.picker-footer span` (used as the `pickerCount` element) has no dedicated class rule — it is styled via the `.picker-footer span` selector in the shared stylesheet. Target it with `$(picker).find('.picker-footer span')` in JS.
</Note>