Light Dark System

Data Select

<zn-data-select> | ZnDataSelect
Since 1.0 experimental

A select component with built-in data providers for common options like colors, currencies, and countries. 


<div class="form-spacing">
  <zn-data-select label="Country" provider="country" name="country" multiple></zn-data-select>
  <zn-data-select label="Currency" provider="currency" name="currency"></zn-data-select>
  <zn-data-select label="Color" provider="color" name="color"></zn-data-select>
</div>

Examples

Data Providers

The component includes built-in providers for common data types.

<div class="form-spacing">
  <zn-data-select label="Country" provider="country" name="country"></zn-data-select>
  <zn-data-select label="Currency" provider="currency" name="currency"></zn-data-select>
  <zn-data-select label="Color" provider="color" name="color"></zn-data-select>
  <zn-data-select label="Phone Prefix" provider="phone" name="phone"></zn-data-select>
</div>

With Default Values

Set a default selected value using the value attribute.

<div class="form-spacing">
  <zn-data-select label="Country" provider="country" name="country" value="GB"></zn-data-select>
  <zn-data-select label="Currency" provider="currency" name="currency" value="USD"></zn-data-select>
  <zn-data-select label="Color" provider="color" name="color" value="blue"></zn-data-select>
</div>

Icon Position

Control where the icon appears using the icon-position attribute. Options are start, end, or none (default). 

<div class="form-spacing">
  <zn-data-select label="Icon at Start" provider="country" name="country" value="GB" icon-position="start"></zn-data-select>
  <zn-data-select label="Icon at End" provider="country" name="country" value="US" icon-position="end"></zn-data-select>
  <zn-data-select label="No Icon" provider="country" name="country" value="FR" icon-position="none"></zn-data-select>
</div>

Icon Only

Display only the icon without text using the icon-only attribute.

<div class="form-spacing">
  <zn-data-select provider="color" name="color" value="red" icon-only></zn-data-select>
  <zn-data-select provider="country" name="country" value="GB" icon-only></zn-data-select>
  <zn-data-select provider="currency" name="currency" value="USD" icon-only></zn-data-select>
</div>

Multiple Selection

Allow selecting multiple options using the multiple attribute.

<div class="form-spacing">
  <zn-data-select label="Countries" provider="country" name="countries" multiple></zn-data-select>
  <zn-data-select label="Currencies" provider="currency" name="currencies" multiple></zn-data-select>
  <zn-data-select label="Colors" provider="color" name="colors" multiple></zn-data-select>
</div>

Clearable

Add a clear button to reset the selection using the clearable attribute.

<div class="form-spacing">
  <zn-data-select label="Country" provider="country" name="country" value="GB" clearable></zn-data-select>
  <zn-data-select label="Currency" provider="currency" name="currency" value="USD" clearable></zn-data-select>
  <zn-data-select label="Color" provider="color" name="color" value="blue" clearable></zn-data-select>
</div>

Filtered Options

Use the filter attribute to show only specific options from the provider.

<div class="form-spacing">
  <zn-data-select label="Major Countries" provider="country" name="country" filter="gb,us,fr,de,jp,cn"></zn-data-select>
  <zn-data-select label="Common Currencies" provider="currency" name="currency" filter="gbp,usd,eur,jpy"></zn-data-select>
  <zn-data-select label="Primary Colors" provider="color" name="color" filter="red,green,blue"></zn-data-select>
</div>

Sizes

Control the size of the select using the size attribute.

<div class="form-spacing">
  <zn-data-select label="Small" provider="country" name="country" size="small" value="GB"></zn-data-select>
  <zn-data-select label="Medium" provider="country" name="country" size="medium" value="US"></zn-data-select>
  <zn-data-select label="Large" provider="country" name="country" size="large" value="FR"></zn-data-select>
</div>

With Help Text

Provide additional context using the help-text attribute.

<div class="form-spacing">
  <zn-data-select label="Country"
                  provider="country"
                  name="country"
                  help-text="Select your country of residence"></zn-data-select>
</div>

Required Field

Mark fields as required using the required attribute.

Submit 
<form>
  <div class="form-spacing">
    <zn-data-select label="Country" provider="country" name="country" required></zn-data-select>
    <zn-data-select label="Currency" provider="currency" name="currency" required></zn-data-select>
    <zn-button type="submit" color="success">Submit</zn-button>
  </div>
</form>

Disabled State

Disable the select using the disabled attribute.

<div class="form-spacing">
  <zn-data-select label="Country" provider="country" name="country" value="GB" disabled></zn-data-select>
  <zn-data-select label="Currency" provider="currency" name="currency" value="USD" disabled></zn-data-select>
</div>

With Label Tooltip

Add a tooltip to the label using the label-tooltip attribute.

<div class="form-spacing">
  <zn-data-select label="Country"
                  provider="country"
                  name="country"
                  label-tooltip="This is used for shipping and tax calculations"></zn-data-select>
</div>

With Context Note

Add contextual information using the context-note attribute.

<div class="form-spacing">
  <zn-data-select label="Currency"
                  provider="currency"
                  name="currency"
                  context-note="Optional"></zn-data-select>
</div>

Placement Options

Control where the dropdown menu appears using the placement attribute.

<div class="form-spacing">
  <zn-data-select label="Opens Below" provider="country" name="country" placement="bottom"></zn-data-select>
  <zn-data-select label="Opens Above" provider="country" name="country" placement="top"></zn-data-select>
</div>

Allow All Option

Include an “All” option at the top of the list using the allow-all attribute.

<div class="form-spacing">
  <zn-data-select label="Country" provider="country" name="country" allow-all></zn-data-select>
  <zn-data-select label="Currency" provider="currency" name="currency" allow-all></zn-data-select>
</div>

Common Currencies

For the currency provider, use allow-common to include a “Common Currencies” option.

<div class="form-spacing">
  <zn-data-select label="Currency" provider="currency" name="currency" allow-common></zn-data-select>
</div>

Complete Form Example

A complete form using data-select components.

Save Preferences 
<form>
  <div class="form-spacing">
    <zn-data-select label="Country"
                    provider="country"
                    name="country"
                    required
                    clearable
                    icon-position="start"
                    help-text="Select your country"></zn-data-select>

    <zn-data-select label="Currency"
                    provider="currency"
                    name="currency"
                    required
                    clearable
                    help-text="Preferred currency for transactions"></zn-data-select>

    <zn-data-select label="Accent Color"
                    provider="color"
                    name="color"
                    icon-position="start"
                    help-text="Choose your preferred theme color"></zn-data-select>

    <zn-button type="submit" color="success">Save Preferences</zn-button>
  </div>
</form>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.72/dist/components/data-select/data-select.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.72/dist/components/data-select/data-select.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/data-select/data-select.js';

Slots

Name Description
label The select’s label. Alternatively, you can use the label attribute.
label-tooltip Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the label-tooltip attribute.
context-note Used to add contextual text that is displayed above the select, on the right. Alternatively, you can use the context-note attribute.
help-text Text that describes how to use the select. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Properties

Name Description Reflects Type Default
name The name of the select. Used for form submission. string -
value The value of the select. Used for form submission. When multiple is enabled, this is an array of strings. string | string[] ''
provider The provider of the select. 'color' | 'currency' | 'country' | 'phone' -
iconPosition
icon-position 		The position of the icon. 'start' | 'end' | 'none' 'none'
filter An array of keys to use for filtering the options in the selected provider. string[] -
size The selects size. 'small' | 'medium' | 'large' 'medium'
clearable Should we show the clear button boolean -
allowAll
allow-all 		Include an “All” option at the top. boolean false
allowCommon
allow-common 		Include a “Common” option that selects multiple common currencies. boolean false
label The selects label. If you need to display HTML, use the label slot instead. string ''
labelTooltip
label-tooltip 		Text that appears in a tooltip next to the label. If you need to display HTML in the tooltip, use the label-tooltip slot instead. string ''
contextNote
context-note 		Text that appears above the input, on the right, to add additional context. If you need to display HTML in this text, use the context-note slot instead. string ''
placement The preferred placement of the selects menu. Note that the actual placement may vary as needed to keep the listbox inside the viewport. 'top' | 'bottom' 'bottom'
helpText
help-text 		The selects help text. If you need to display HTML, use the help-text slot instead. string ''
required The selects required attribute. boolean false
disabled Disables the select. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
zn-input Emitted when the select’s value changes. -
zn-clear Emitted when the clear button is activated. -
blur Emitted when the select loses focus. -

Learn more about events.

Parts

Name Description
combobox The container that wraps the prefix, combobox, clear icon, and expand button (forwarded from zn-select).
expand-icon The container that wraps the expand icon (forwarded from zn-select).
form-control-help-text The help text’s wrapper (forwarded from zn-select).
form-control-input The select’s wrapper (forwarded from zn-select).
display-input The element that displays the selected option’s label (forwarded from zn-select).

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <zn-example>
  • <zn-icon>
  • <zn-option>
  • <zn-popup>
  • <zn-select>
  • <zn-tag>