Make a selection using a dropdown.
<!-- for demo only -->
<tk-highlight id="exampleSelectOutput" class="l-block"></tk-highlight>
<tk-select
id="exampleSelect"
options="defaultOptions"
>
<span slot="label" class="l-block t-heavy">Character</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
loadScript(document.currentScript);
exampleSelect.addEventListener('valueChanged', ($event) => {
exampleSelectOutput.innerHTML = `📣 valueChanged emitted: ${$event.detail}`;
});
</script>
This dropdown text pattern is primarily used in forms to make a selection. The width is tied to the option with the longest character count.
<tk-select options="defaultOptions">
<span slot="label" class="l-block t-heavy">Medium Label</span>
</tk-select>
<hr/>
<tk-select options="defaultOptions">
<span slot="label" class="l-block t-large t-heavy">Large Label</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
loadScript(document.currentScript);
</script>
Provide a label for the component by slotting a span
element as shown in the example. The text size of the label can be controlled with our typography utility classes.
<tk-select options="defaultOptions">
<span slot="label" class="l-block t-heavy">Character</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
let options = [
{
"label": "House Gryffindor",
"options": [
{ "label": "Hermione Granger", "value": "Value5" },
{ "label": "Ron Weasley", "value": "Value7" },
{ "label": "Harry Potter", "value": "Value6" }
]
},
{
"label": "House Slytherin",
"options": [
{ "label": "Draco Malfoy", "value": "Value8"}
]
},
{
"options": [
{ "label": "Albus Dumbledore", "value": "Value1"},
{ "label": "Severus Snape", "value": "Value4" }
]
},
];
loadScript(document.currentScript, options);
</script>
A native select
allows for grouping its options with an optgroup
tag. To achieve this for tk-select
, add a "label": "Label here"
key/value pair inside of the options data model. Expand the code example for more details.
<tk-select
options="defaultOptions"
type="secondary"
>
<span slot="label" class="l-block t-heavy">Secondary type</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
loadScript(document.currentScript);
</script>
<hr>
<tk-select
options="defaultOptions"
type="outline"
>
<span slot="label" class="l-block t-heavy">Outline type</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
loadScript(document.currentScript);
</script>
The component comes in different types of appearances. Pass the desired value for the type
prop to render it accordingly.
<tk-select value="Value6" options="defaultOptions">
<span slot="label" class="l-block t-heavy">Character</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
loadScript(document.currentScript);
</script>
Pass tk-select
a value prop which matches the value of the option that you’d like prefilled.
<tk-select
options="defaultOptions"
type="secondary"
class="mb-2x"
>
<span slot="label" class="l-block t-heavy">Size: determined by widest option</span>
</tk-select>
<hr>
<tk-select
options="defaultOptions"
type="secondary"
class="mb-2x l-block"
>
<span slot="label" class="l-block t-heavy">Size: util class</span>
</tk-select>
<hr>
<div class="l-grid l-col-3 l-sm-col-1 l-gap-2x">
<tk-select
options="defaultOptions"
type="secondary"
class="l-block"
>
<span slot="label" class="l-block t-heavy">Size: util class</span>
</tk-select>
<tk-select
options="defaultOptions"
type="secondary"
class="l-block"
>
<span slot="label" class="l-block t-heavy">Size: util class</span>
</tk-select>
<tk-select
options="defaultOptions"
type="secondary"
class="l-block"
>
<span slot="label" class="l-block t-heavy">Size: util class</span>
</tk-select>
</div>
<hr>
<tk-select
options="defaultOptions"
type="secondary"
class="mb-2x l-block"
size="large"
>
<span slot="label" class="l-block t-heavy">Size: Large</span>
</tk-select>
<script>
loadScript(document.currentScript);
</script>
By default, the width of a select is tied to the option with the longest character count. To change the width, the util class l-block
can be used to make a select as wide as its parent.
<tk-select
options="defaultOptions"
error
>
<span slot="label" class="l-block t-heavy">Error state</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
loadScript(document.currentScript);
</script>
To render the component in a failed validation state, pass an error
prop.
<tk-select
options="defaultOptions"
disabled
>
<span slot="label" class="l-block t-heavy">Disabled state for entire menu</span>
</tk-select>
<hr>
<tk-select options="defaultOptions">
<span slot="label" class="l-block t-heavy">Disabled state for individual options</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
options = [
{
"options": [
{ "label": "Hermione Granger", "value": "Value5" },
{ "label": "Ron Weasley", "value": "Value7", "disabled": true },
{ "label": "Harry Potter", "value": "Value6" }
]
},
];
const components = document.currentScript.parentNode.querySelectorAll('tk-select');
components[0].options = defaultOptions;
components[1].options = options;
</script>
If the entire tk-select
menu needs to be rendered in a disabled state, pass the disabled
prop.
If you need this for individual options, add a "disabled": true
key/value pair inside of the options data model. Expand the code example for more details.
<tk-select
options="defaultOptions"
required
>
<span slot="label" class="l-block t-heavy">Character (required)</span>
</tk-select>
<script>
options = [
{
"options": [
{ "label": "Please select", "value": ""},
...defaultOptions[0].options
]
},
];
loadScript(document.currentScript, options);
</script>
If the tk-select
is required to have a value and can’t be left empty, pass a required
prop. This will also render validation styling.
<tk-select options="defaultOptions">
<span slot="label" class="l-block t-heavy">Character</span>
<span slot="hint" class="l-inline-flex l-v-center">
<tk-icon name="heart" size="xs" class="mr-1x" variant="solid"></tk-icon>
Select your favourite character
</span>
</tk-select>
<hr>
<tk-select
options="defaultOptions"
error
>
<span slot="label" class="l-block t-heavy">Character</span>
<span slot="hint" class="l-inline-flex l-v-center">
<tk-icon name="heart" size="xs" class="mr-1x" variant="solid"></tk-icon>
Select your favourite character
</span>
</tk-select>
<script>
loadScript(document.currentScript);
</script>
The tk-select
renders a hint containing any content injected into the hint
slot, when supplied. When the error
prop is also true, the hint is rendered in error state, aria-invalid="true"
is added to the select
and the aria-errormessage
value of the select
is set to the id of the tk-select
.
<tk-select options="defaultOptions">
<span slot="label" class="l-block t-heavy">Default text size</span>
</tk-select>
<hr>
<tk-select
options="defaultOptions"
size="medium"
>
<span slot="label" class="l-block t-heavy">Medium text size</span>
</tk-select>
<!-- only required for use outside of a framework -->
<script>
loadScript(document.currentScript);
</script>
Set the size
prop to medium
to set the font size within the select to 16px. By default, the size is 14px.
Selects should have a descriptive label. It can be passed to the component by using a span
element with a slot="label"
attribute on it. Code examples provided above.
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
autoFocus |
auto-focus |
When passed, it specifies that the select should automatically get focus when the page loads. | boolean |
false |
disabled |
disabled |
Displays the select in a disabled style and disables input. | boolean |
false |
error |
error |
Displays the select in an error style. | boolean |
false |
labelSize |
label-size |
Deprecated! Please use the label slot instead. Changes the size of the label, can be set to either medium or large . |
string |
undefined |
labelText |
label-text |
Deprecated! Please use the label slot instead. If present, the value of this prop is rendered inside a <label> above the select. |
string |
undefined |
options |
– | Array of options to render as children of the select. Supports grouping of options. | SelectOption[] |
undefined |
required |
required |
Should be set if required before user can proceed. Will also trigger validation styles. | boolean |
false |
size |
size |
Adjusts the size of the text in the select to medium. Size is small by default. | "large" | "medium" | "small" | "xl" |
'small' |
type |
type |
Determines which type of select is rendered | "default" | "outline" | "secondary" |
'default' |
value |
value |
Used to prefill the select. Pass the value of the option that you’d like prefilled. | string |
undefined |
Event | Description | Type |
---|---|---|
valueChanged |
This event is fired every time the select is changed, it receives a string of what is in the select box. | CustomEvent<string> |