nb-select
This is a select component for Vue.js 3+.
Loading component...
Installation
yarn add @vlalg-nimbus/nb-selects
Usage
import { createApp } from 'vue'
import App from './App.vue'
import NbSelectComponents from '@vlalg-nimbus/nb-selects'
import "@vlalg-nimbus/nb-selects/dist/style.css";
const app = createApp(App)
app.use(NbSelectComponents)
app.mount('#app')
To use, simply call the component, in this case it will be NbSelect or nb-select.
<template>
<NbSelect />
</template>
Preview & Playground
Select the component you want to edit/test
Props
Items with an (*) mean they are required
| name | Value type | Default | Description |
|---|---|---|---|
| nbId (*) | String | Sets the id attribute to differentiate from other components | |
| selectName | String | 'selectX' | Sets the name attribute for the select element |
| display | String | 'b' | Defines the display type. Accepts ib and b. |
| theme | String | 'light' | Defines the theme. Accepts dark and light. When theme is set, uses theme-specific color props. |
| hasBorderRadius | Boolean | false | Defines if the select should have border-radius. |
| borderRadius | Number | 0.5 | Defines border-radius. |
| disabled | Boolean | false | Defines if the select is disabled |
| required | Boolean | false | Defines if the select is required |
| fontFamily | String | "'Lato', sans-serif" | Defines the font-family |
| fontSize | String | '1.6em' | Defines the font-size |
| fontWeight | Number | 400 | Defines the font-weight |
| textAlign | String | 'left' | Defines the text alignment. Accepts left, center, right. |
| selectWidth | Number | 200 | Defines the select width in pixels |
| inputStyle | String | 'background' | Defines the input style. Accepts background, line, border. |
| options | Array | Defines the list of options. It is an array of objects with value and text properties (or custom keys via valueKey and textKey). For grouped display, add a property with the key given by groupKey (e.g. group) on each option. | |
| selectedOptionOnly | String, Number, Boolean | '' | Defines the selected value for single select. The value must exist in the list options |
| selectedOptionMultiple | Array | Defines the selected values for multiple select. The values must exist in the list options | |
| textKey | String | 'text' | Defines the key name for the text property in options objects |
| valueKey | String | 'value' | Defines the key name for the value property in options objects |
| groupKey | String | '' | Key name for the group property in options objects. Used with hasGroups to show options grouped by this value. |
| hasGroups | Boolean | false | When true and groupKey is set, options are displayed in groups; each group shows a label (the group value) and its options below. |
| groupCollapsible | Boolean | false | When true and hasGroups is enabled, clicking on a group header toggles collapsing/expanding that group's options. |
| multiple | Boolean | false | Defines if the select allows multiple selections |
| hasEmptyOption | Boolean | true | Defines if the select should have an empty option (placeholder). In single select it selects the empty value; in multiple select it appears as the first option in the list and clears the selection when clicked. Hidden when the filter has text (same as single). |
| emptyOptionText | String | 'Select an option' | Defines the text for the empty option |
| emptyOptionValue | String, Number | null | Defines the value for the empty option |
| hasFilter | Boolean | false | Enables a filter input at the top of the dropdown to search/filter options |
| filterPlaceholder | String | 'Filter...' | Placeholder text for the filter input |
| emptyFilterText | String | 'not found' | Text shown when the filter returns no results |
| multipleSelectedText | String | 'items selected' | Text shown in the field when multiple options are selected (e.g. "3 items selected"). The number is prepended automatically. |
| filterPadding | String | '8px' | Padding of the filter wrap area |
| filterMarginBottom | Number | 0 | Bottom margin of the filter wrap in pixels |
| filterBorderRadius | Number | 0 | Border radius of the filter input (in rem) |
| optionsPadding | String | '8px 12px' | Padding applied to each option item in the dropdown list (single and multiple) |
| groupPadding | String | '6px 8px' | Padding applied to each group label header when using grouped display (hasGroups + groupKey). |
| dropdownScrollClass | String | '' | Defines a custom CSS class for the dropdown scroll container |
| showLabel | Boolean | false | Defines if the select should have a label |
| label | String | 'Label text' | Defines the label text |
| labelMarginBottom | Number | 0 | Defines the bottom margin of the label in pixels |
| labelMarginLeft | Number | 0 | Defines the left margin of the label in pixels |
| fontFamilyLabel | String | "'Lato', sans-serif" | Defines the font-family for the label |
| fontSizeLabel | String | '1em' | Defines the font-size for the label |
| fontWeightLabel | Number | 400 | Defines the font-weight for the label |
| fontSizeLabelActive | String | '0.8em' | Defines the font-size for the label when active |
| labelBackground | String | 'transparent' | Defines the background color for the label when active |
| labelPadding | String | '1px 5px' | Defines the padding for the label when active |
| labelBorderRadius | Number | 0 | Defines the border-radius for the label when active |
| labelLeft | Number | 5 | Defines the left position of the label in pixels |
| labelActiveTop | Number | -13 | Defines the top position of the label when active in pixels |
| labelActiveLeft | Number | 5 | Defines the left position of the label when active in pixels |
| labelRight | Number | 0 | Defines the right position of the label in pixels |
| labelActiveRight | Number | 0 | Defines the right position of the label when active in pixels |
| inputLabelMarginActive | Number | 15 | Defines the top margin of the input when the label is active in pixels |
| labelBreakOnActive | Boolean | true | Defines if the label text should break or use ellipsis when active |
| tabIndex | Number | 0 | Defines the tab index. Set this property to make the select focusable by the keyboard. |
| hasTabIndexEnter | Boolean | true | Enables the select to be activated with the Enter key when focused. |
| hasTabIndexSpace | Boolean | true | Enables the select to be activated with the Space key when focused. |
| ariaLabel | String | 'Select' | Defines the aria-label attribute for screen readers. |
| ariaAttrs | Object | {} | Allows passing custom aria attributes as an object. Keys will automatically receive the aria- prefix. Example: { 'describedby': 'help-id', 'invalid': 'false' } |
| title | String | '' | Tooltip text shown when hovering over the component. |
| lightBgColor | String | '#f8f8f2' | Defines the background color for light theme. Accepts Color name and Hex |
| lightBgColorFocus | String | '#eaeaea' | Defines the background color on focus for light theme. Accepts Color name and Hex |
| lightBorderColor | String | '#353734' | Defines the border color for light theme. Accepts Color name and Hex |
| lightBorderColorFocus | String | '#272936' | Defines the border color on focus for light theme. Accepts Color name and Hex |
| lightDisabledBgColor | String | '#dfdfd9' | Defines the disabled background color for light theme. Accepts Color name and Hex |
| lightTextColor | String | '#000000' | Defines the text color for light theme. Accepts Color name and Hex |
| lightDisabledBorderColor | String | 'rgba(53, 55, 52, 0.3)' | Defines the disabled border color for light theme. Accepts Color name and Hex |
| lightOptionTextColor | String | '#000000' | Defines the option text color for light theme. Accepts Color name and Hex |
| lightOptionTextColorSelected | String | '#000000' | Defines the selected option text color for light theme. Accepts Color name and Hex |
| lightOptionBgColorSelected | String | '#e0e0e0' | Defines the selected option background color for light theme. Accepts Color name and Hex |
| lightPlaceholderColor | String | '#999999' | Defines the placeholder color for light theme. Accepts Color name and Hex |
| lightFilterTextColor | String | '#000000' | Defines the filter input and selected-value text color for light theme. Accepts Color name and Hex |
| lightEmptyTextColor | String | '#999999' | Defines the empty/placeholder text color (dropdown placeholder, filter placeholder, "not found" message) for light theme. Accepts Color name and Hex |
| lightFilterWrapBorderColor | String | '#353734' | Defines the border color of the filter wrap (area above the list) for light theme. If empty, uses lightBorderColor. Accepts Color name and Hex |
| lightFilterInputBorderColor | String | '#353734' | Defines the border color of the filter input for light theme. If empty, uses lightBorderColor. Accepts Color name and Hex |
| lightGroupTextColor | String | '' | Defines the text color of the group header label for light theme. If empty, uses lightPlaceholderColor. Accepts Color name and Hex |
| lightGroupBgColor | String | '' | Defines the background color of the group header label for light theme. If empty, uses transparent. Accepts Color name and Hex |
| lightTextColorLabel | String | '#333333' | Defines the label text color for light theme. Accepts Color name and Hex |
| lightTextColorLabelActive | String | '#333333' | Defines the label text color when active for light theme. Accepts Color name and Hex |
| darkBgColor | String | '#353734' | Defines the background color for dark theme. Accepts Color name and Hex |
| darkBgColorFocus | String | '#272936' | Defines the background color on focus for dark theme. Accepts Color name and Hex |
| darkBorderColor | String | '#44475a' | Defines the border color for dark theme. Accepts Color name and Hex |
| darkBorderColorFocus | String | 'rgba(68, 71, 90, 0.4)' | Defines the border color on focus for dark theme. Accepts Color name and Hex |
| darkDisabledBgColor | String | 'rgba(40, 42, 54, 1)' | Defines the disabled background color for dark theme. Accepts Color name and Hex |
| darkTextColor | String | '#ffffff' | Defines the text color for dark theme. Accepts Color name and Hex |
| darkDisabledBorderColor | String | 'rgba(68, 71, 90, 0.3)' | Defines the disabled border color for dark theme. Accepts Color name and Hex |
| darkOptionTextColor | String | '#ffffff' | Defines the option text color for dark theme. Accepts Color name and Hex |
| darkOptionTextColorSelected | String | '#ffffff' | Defines the selected option text color for dark theme. Accepts Color name and Hex |
| darkOptionBgColorSelected | String | '#3d3d3d' | Defines the selected option background color for dark theme. Accepts Color name and Hex |
| darkPlaceholderColor | String | '#999999' | Defines the placeholder color for dark theme. Accepts Color name and Hex |
| darkFilterTextColor | String | '#ffffff' | Defines the filter input and selected-value text color for dark theme. Accepts Color name and Hex |
| darkEmptyTextColor | String | '#999999' | Defines the empty/placeholder text color (dropdown placeholder, filter placeholder, "not found" message) for dark theme. Accepts Color name and Hex |
| darkFilterWrapBorderColor | String | '#44475a' | Defines the border color of the filter wrap (area above the list) for dark theme. If empty, uses darkBorderColor. Accepts Color name and Hex |
| darkFilterInputBorderColor | String | '#44475a' | Defines the border color of the filter input for dark theme. If empty, uses darkBorderColor. Accepts Color name and Hex |
| darkGroupTextColor | String | '' | Defines the text color of the group header label for dark theme. If empty, uses darkPlaceholderColor. Accepts Color name and Hex |
| darkGroupBgColor | String | '' | Defines the background color of the group header label for dark theme. If empty, uses transparent. Accepts Color name and Hex |
| darkTextColorLabel | String | '#ffffff' | Defines the label text color for dark theme. Accepts Color name and Hex |
| darkTextColorLabelActive | String | '#ffffff' | Defines the label text color when active for dark theme. Accepts Color name and Hex |
| maxHeight | Number | 200 | Defines the maximum height (in pixels) of the dropdown list. Minimum value is 37.58px (when hasEmptyOption is false) or 75.16px (when hasEmptyOption is true) |
Events
| name | Return type | Description |
|---|---|---|
| changed | value | Fired when the selected value changes, returns the selected value(s). |
| changed-complete | { value|values, option|options, index|indices } | Fired together with changed, but returns the full option object(s) and index/indices in the options array. For multiple selects, values/options/indices are arrays. |
| user-changed | value | Fired when the user manually changes the selected value, returns the selected value(s). |
| user-changed-complete | { value|values, option|options, index|indices } | Fired together with user-changed, but returns the full option object(s) and index/indices in the options array. For multiple selects, values/options/indices are arrays. |
| clicked | MouseEvent | KeyboardEvent | Fired when the select is clicked. Receives the native DOM event as first argument. |
| clicked-complete | { event, value|values, option|options, index|indices } | Fired together with clicked, returns the original event and the current selection meta (full option object(s) and index/indices in the options array). |
| focused | nothing | Fired when the select component receives focus (when clicking on the select field or navigating to it via keyboard). |
| blurred | nothing | Fired when the select component loses focus (when clicking outside or navigating away via keyboard). |
Slot
The component has a slot called slot-select-item where you can customize the display of each option.
<template>
<NbSelect
nb-id="select-custom"
select-name="select-custom"
:options="selectOptions"
:selected-option-only="selectedValue"
>
<template #slot-select-item="{ propRow, propIndex }">
<div>
<strong>{{ propRow.text }}</strong>
<span style="color: #999;"> - {{ propRow.description }}</span>
</div>
</template>
</NbSelect>
</template>
Example
Light Theme (default)
<template>
<NbSelect
nb-id="select-light"
select-name="select-light"
theme="light"
:options="selectOptions"
:selected-option-only="selectedValue"
light-bg-color="#dbeafe"
light-bg-color-focus="#bfdbfe"
light-border-color="#93c5fd"
light-border-color-focus="#60a5fa"
light-text-color="#1e40af"
light-placeholder-color="#64748b"
light-option-text-color="#1e40af"
light-option-text-color-selected="#ffffff"
light-option-bg-color-selected="#3b82f6"
:border-radius="0.375"
@changed="handleChange($event)"
@user-changed="handleUserChange($event)"
/>
</template>
<script setup>
import { ref } from 'vue';
defineOptions({
name: 'CompSelect',
});
const selectOptions = [
{ value: 'option1', text: 'Option 1' },
{ value: 'option2', text: 'Option 2' },
{ value: 'option3', text: 'Option 3' }
];
const selectedValue = ref('option1');
const handleChange = (value) => {
selectedValue.value = value;
console.log('Changed:', value);
};
const handleUserChange = (value) => {
console.log('User changed:', value);
};
</script>
Dark Theme
<template>
<NbSelect
nb-id="select-dark"
select-name="select-dark"
theme="dark"
:options="selectOptions"
:selected-option-only="selectedValue"
dark-bg-color="#8b5cf6"
dark-bg-color-focus="#7c3aed"
dark-border-color="#a78bfa"
dark-border-color-focus="#8b5cf6"
dark-text-color="#f3f4f6"
dark-placeholder-color="#c4b5fd"
dark-option-text-color="#f3f4f6"
dark-option-text-color-selected="#ffffff"
dark-option-bg-color-selected="#6d28d9"
:border-radius="0.5"
@changed="handleChange($event)"
@user-changed="handleUserChange($event)"
/>
</template>
<script setup>
import { ref } from 'vue';
defineOptions({
name: 'CompSelectDark',
});
const selectOptions = [
{ value: 'option1', text: 'Option 1' },
{ value: 'option2', text: 'Option 2' },
{ value: 'option3', text: 'Option 3' }
];
const selectedValue = ref('option2');
const handleChange = (value) => {
selectedValue.value = value;
console.log('Changed:', value);
};
const handleUserChange = (value) => {
console.log('User changed:', value);
};
</script>
Multiple Selection
<template>
<NbSelect
nb-id="select-multiple"
select-name="select-multiple"
theme="light"
:multiple="true"
:options="selectOptions"
:selected-option-multiple="selectedValues"
@changed="handleChange($event)"
@user-changed="handleUserChange($event)"
/>
</template>
<script setup>
import { ref } from 'vue';
defineOptions({
name: 'CompSelectMultiple',
});
const selectOptions = [
{ value: 'option1', text: 'Option 1' },
{ value: 'option2', text: 'Option 2' },
{ value: 'option3', text: 'Option 3' }
];
const selectedValues = ref(['option1', 'option2']);
const handleChange = (value) => {
selectedValues.value = value;
console.log('Changed:', value);
};
const handleUserChange = (value) => {
console.log('User changed:', value);
};
</script>
Grouped options
When has-groups is true and group-key is set, options are displayed in groups. Each option object must include the group key (e.g. group).
<template>
<NbSelect
nb-id="select-groups"
select-name="select-groups"
theme="light"
:options="selectOptionsWithGroups"
:selected-option-only="selectedValue"
group-key="group"
:has-groups="true"
@changed="handleChange($event)"
/>
</template>
<script setup>
import { ref } from 'vue';
const selectOptionsWithGroups = [
{ value: 'a1', text: 'Option A1', group: 'Group A' },
{ value: 'a2', text: 'Option A2', group: 'Group A' },
{ value: 'b1', text: 'Option B1', group: 'Group B' },
{ value: 'b2', text: 'Option B2', group: 'Group B' }
];
const selectedValue = ref('a1');
const handleChange = (value) => {
selectedValue.value = value;
};
</script>
Behavior
Auto-close
The component dropdown closes automatically in two situations:
- When focus leaves the component: When using Tab to navigate away from the component or clicking on another element on the page, the dropdown closes automatically.
- When another select is opened: When opening a new select (single or multiple), all other open selects close automatically. This ensures only one select is open at a time.
Multiple mode
In multiple mode (multiple="true"), the dropdown stays open after selecting an option, allowing you to select multiple options without reopening the dropdown. The dropdown only closes when:
- Focus leaves the component
- Another select is opened
- You click outside the component (left-click; right-click does not close it)
When hasEmptyOption is enabled, the empty option appears as the first row in the list in multiple mode; clicking it clears the selection (equivalent to "deselect all").
Limitations
Overflow Hidden
The component dropdown uses position: absolute for positioning. If the component is inside a parent container with overflow: hidden, the dropdown may be clipped or hidden.
Solution: Remove or adjust the overflow: hidden property on the component's parent container so the dropdown can be displayed correctly.
<!-- ❌ Problem: dropdown will be clipped -->
<div style="overflow: hidden;">
<NbSelect nb-id="select-1" :options="options" />
</div>
<!-- ✅ Solution: remove overflow: hidden or use overflow: visible -->
<div style="overflow: visible;">
<NbSelect nb-id="select-1" :options="options" />
</div>
