oziSelect

Version: 5.0.0 — Updated: 2026-05-27

Description

Custom selection plugin for web interfaces, developed to replace traditional selects with a richer, more visual and flexible experience. Allows working with single or multiple selection, displaying items with images, text or custom HTML, organizing options by groups and integrating the selection directly with forms through hidden fields automatically generated from any field present in the options JSON.

Supports local search and remote search, enabling filtering of existing options in the browser or querying new results from the server as the user types. Recommended for scenarios where a standard select doesn't offer enough flexibility — such as lists with images, multiple choices with visual tags, option grouping and dynamic loading via AJAX.

Examples

[1] Simple selection

<div data-ozi-select="states"></div>

<script type="application/json" data-ozi-select-options="states">
[
    { "value": "AL", "label": "Alabama" },
    { "value": "CA", "label": "California" },
    { "value": "TX", "label": "Texas" }
]
</script>

[2] With icons

Use data-ozi-select-value-icon and data-ozi-select-search-icon with any icon library.

<div
    data-ozi-select="states"
    data-ozi-select-value-placeholder="Select a state..."
    data-ozi-select-value-icon="bi bi-geo-alt"
    data-ozi-select-search-placeholder="Search..."
    data-ozi-select-search-icon="bi bi-search">
</div>

[3] With image

Use the image field in JSON to display images in options, preview and tags.

<div
    data-ozi-select="countries"
    data-ozi-select-value-placeholder="Select a country..."
    data-ozi-select-value-icon="bi bi-globe"
    data-ozi-select-search-icon="bi bi-search"
    data-ozi-select-list="150px">
</div>

<script type="application/json" data-ozi-select-options="countries">
[
    { "value": "US", "label": "United States", "labelHtml": "Americas", "image": "/image/flags/us.jpg" },
    { "value": "GB", "label": "United Kingdom", "labelHtml": "Europe",   "image": "/image/flags/gb.jpg" }
]
</script>

[4] Multiple selection

<div
    data-ozi-select="states"
    data-ozi-select-multiple
    data-ozi-select-value-placeholder="Select states..."
    data-ozi-select-value-icon="bi bi-geo-alt"
    data-ozi-select-search-icon="bi bi-search"
    data-ozi-select-list="150px">
</div>

<script type="application/json" data-ozi-select-options="states">
[
    { "value": "CA", "label": "California", "labelHtml": "West" },
    { "value": "TX", "label": "Texas",      "labelHtml": "South" }
]
</script>

[5] Multiple with groups

Use the group field in JSON to organize options into visual groups.

<div
    data-ozi-select="states"
    data-ozi-select-multiple
    data-ozi-select-list="220px">
</div>

<script type="application/json" data-ozi-select-options="states">
[
    { "value": "WA", "label": "Washington", "group": "West" },
    { "value": "TX", "label": "Texas",      "group": "South" },
    { "value": "NY", "label": "New York",   "group": "Northeast" }
]
</script>

[6] Select all by group

Use data-ozi-select-multiple-group — click on the group to select or remove all items at once.

<div
    data-ozi-select="states"
    data-ozi-select-multiple-group
    data-ozi-select-list="220px"
    data-ozi-select-required>
</div>

[7] Remote search — minimal

Use data-ozi-select-zld-url to fetch options via AJAX. The initial JSON is empty.

<div
    data-ozi-select="states"
    data-ozi-select-multiple-group
    data-ozi-select-zld-url="/api/states">
</div>

<script type="application/json" data-ozi-select-options="states">[]</script>

[8] Remote search — full

POST with extra parameters, images, delay and log enabled.

<div
    data-ozi-select="states"
    data-ozi-select-multiple-group
    data-ozi-select-value-placeholder="Select states..."
    data-ozi-select-image-dimension="50px,40px"
    data-ozi-select-zld-url="/api/states/search"
    data-ozi-select-zld-method="POST"
    data-ozi-select-zld-param="search"
    data-ozi-select-zld-item-name="company_id:15, status:active"
    data-ozi-select-zld-min="1"
    data-ozi-select-zld-delay="0"
    data-ozi-select-zld-log="true">
</div>

<script type="application/json" data-ozi-select-options="states">[]</script>

Features

• Single or multiple selection — with visual tags in multiple mode
• Customizable icons — value-icon and search-icon with any library
• Custom HTML — displays images, subLabel or HTML in options and preview
• Option grouping — group field in JSON organizes visually
• Select by group — multiple-group selects/removes all items in a group
• Local search — filters options already loaded in the browser
• Remote search — queries the server via AJAX as the user types
• Automatic hidden inputs — any JSON field becomes a hidden input
• Validation — required field support with custom message
• Full public API — get, set, open, close, enable, disable and more

HTML Attributes

NEW FEATURE

• data-ozi-select-as → maps fields from external JSON to the plugin's canonical names (value, label, image, etc.), allowing consumption of any API without transforming data on the backend.

  • Format: "canonical=alias, canonical=alias"
  • Example: data-ozi-select-as="value=code, label=name, group=region"

[1] Identification

[2] JSON Data — Option Fields

[3] Selection Mode

[4] Placeholders and Visual

[5] Data Submission

[6] State and Validation

[7] Remote Search

Public API

ozi:change event

$('[data-ozi-select="states"]').on('ozi:change', function(e, items, instance, detail) {
    console.log(detail.value);  // selected value
    console.log(detail.items);  // array of selected items
});