Ladderized Select
Ladderized select is for selecting options organized in hierarchical groups. It is ideal for large or categorized lists, and supports deeply nested sublevels and subtext for each item.
Basic Usage
V-Model: []<template>
<spr-select-ladderized
id="ladderized-select"
v-model="laderrizedSelectModel"
:options="options"
label="Ladderized Select"
placeholder="Select an item"
/>
</template>
<script lang="ts" setup>
import { ref } from 'vue';
const laderrizedSelectModel = ref([]);
const options = ref([
{
text: 'Tiger',
value: 'tiger',
subtext: 'Rawr of the jungle',
},
{
text: 'Lion',
value: 'lion',
subtext: 'King of the jungle',
sublevel: [
{
text: 'Cub',
value: 'cub',
subtext: 'Young lion',
sublevel: [
{ text: 'Cub 1', value: 'cub1' },
{ text: 'Cub 2', value: 'cub2' },
],
},
{
text: 'Pride Member',
value: 'pride-member',
subtext: 'Member of a lion pride',
},
],
},
{
text: 'Elephant',
value: 'elephant',
subtext: 'Largest land animal',
sublevel: [
{
text: 'Calf',
value: 'calf',
subtext: 'Young elephant',
},
],
},
{
text: 'Giraffe',
value: 'giraffe',
subtext: 'Tallest living terrestrial animal',
sublevel: [
{
text: 'Calf',
value: 'giraffe-calf',
subtext: 'Young giraffe',
},
{
text: 'Adult',
value: 'giraffe-adult',
subtext: 'Mature giraffe',
},
],
},
{
text: 'Zebra',
value: 'zebra',
subtext: 'Known for distinctive black and white stripes',
sublevel: [
{
text: 'Foal',
value: 'zebra-foal',
subtext: 'Young zebra',
},
{
text: 'Mare',
value: 'zebra-mare',
subtext: 'Adult female zebra',
},
],
},
]);
</script>The options can contain nested sublevels, allowing for complex hierarchies. Each item's sublevel property can itself contain further sublevels, supporting infinite nesting. Each item can have a text, value, and optional subtext for additional information.
Here is an basic json structure of the options:
[
{
"text": <Text>,
"value": <Value>,
"subtext": <Sub Text>,
"sublevel": [
{
"text": <Text>,
"value": <Value>,
"subtext": <Sub Text>,
"sublevel": [
{
"text": <Text>,
"value": <Value>,
"subtext": <Sub Text>,
"sublevel": [...]
},
]
},
...
]
}
...
]Pre-Selected Items
To preselect an item in the ladderized select, the model value array should represent the path to the item in order. For example:
['lion', 'cub', 'cub1'];- The first value is the parent options (
lion). - The second value is the sub-options of
lion(cub). - The third value is the sub-options of
cub(cub1).
V-Model: [
"lion",
"cub",
"cub1"
]Searchable Options
To enable searching through the options, set the searchable-options prop to true. This allows users to filter options by typing in the input field.
You can also pass a searchable-options-placeholder prop to customize the placeholder text for the search input.
V-Model: []<template>
<spr-select-ladderized
id="ladderized-select"
v-model="laderrizedSelectModel"
:options="options"
label="Ladderized Select"
placeholder="Select an item"
searchable-options
/>
</template>Placements
Placement refers to where the select popper will be positioned relative to its trigger element (e.g., button, input field). Pass the placement props to modify the placement of the select popper.
The available placement options are: auto, auto-start, auto-end, top, top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, and left-end.
The default placement is bottom.
Clearable
To allow users to clear the selected value, set the clearable prop to true. This will display a clear (x) icon next to the selected value, which can be clicked to reset the selection.
V-Model: []<template>
<spr-select-ladderized
id="ladderized-select"
v-model="laderrizedSelectModel"
:options="options"
label="Ladderized Select"
placeholder="Select an item"
clearable
/>
</template>Width and Popper Width
You can modify the width of the select component in two ways: by adjusting the width of the select wrapper or by changing the width of the select popper.
Width - Is the overall width wrapper of both parent element and popper element.
Popper Width - Width of only popper element
<template>
<spr-select-ladderized
id="ladderized-select"
v-model="laderrizedSelectModel"
:options="options"
label="Ladderized Select"
placeholder="Select an item"
width="50%"
popper-width="200px"
/>
</template>Popper Strategy
The Popper strategy is primarily used when working with elements like modal. It helps control the positioning behavior of popper. The strategy ensures that the popper element is dynamically positioned based on the viewport, the reference element, or other factors such as scrolling or resizing.
By default, the Popper strategy is set to absolute, which positions the popper element relative to the nearest positioned ancestor (usually the body element). However, you can change the strategy to fixed, which positions the popper element relative to the viewport, ensuring that it remains in place even when the page is scrolled.
Pass the prop popper-strategy to change the behavior position of the popper.
Important to note:
Do not forget to pass prop wrapperPosition to overwrite relative position into initial.
<template>
<spr-button tone="success" @click="modalModel = true">Open Modal</spr-button>
<spr-modal v-model="modalModel" title="Select with Modal">
<spr-select-ladderized
id="ladderized-select"
v-model="laderrizedSelectModel"
label="Ladderized Select"
placeholder="Select an item"
:options="options"
wrapper-position="initial"
popper-strategy="fixed"
/>
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.
</p>
</spr-modal>
</template>Active & Disabled
This is only applicable to selected components, such as form input fields. You can learn more in the Input Form.
To disable the popper from showing when the wrapper is clicked, pass the disabled prop.
API Reference
| Name | Description | Type | Default |
|---|---|---|---|
id | Unique id for the select. Required to bind popper within the select. | String | — |
v-model | Value binding for the select. Accepts array of strings. | Array | [] |
options | List of options (with optional sublevel for hierarchy) | Array | [] |
label | Input label | String | '' |
placeholder | Input placeholder | String | '' |
helperText | Helper text below input | String | '' |
helperIcon | Icon for helper text | String | null |
displayHelper | Show helper text | Boolean | false |
clearable | Show clear (x) icon to remove the selected value | Boolean | false |
placement | Popper placement (e.g., 'bottom', 'top', 'auto', etc.) | String | bottom |
wrapperPosition | CSS position of wrapper | String | relative |
width | Width of the select wrapper | String | 100% |
popperWidth | Width of the select popper | String | 100% |
popperStrategy | Popper positioning strategy ('absolute' or 'fixed') | String | absolute |
disabled | Disable the select | Boolean | false |
removeCurrentLevelInBackLabel | Hide current level in back label | Boolean | false |
searchable-options | Enable search input for filtering options | Boolean | false |
searchable-options-placeholder | Placeholder of the searh options | String | 'Search...' |
Events
| Event | Payload | Description |
|---|---|---|
@update:modelValue | Array | String | Number | Object | Emitted when the selection changes. Payload is the new selected value(s). |