SelectV2
The SelectV2
component allows you to choose one or multiple options from a
collapsed dropdown with options.
Import
import { SelectV2 } from '@dynatrace/strato-components-preview/forms';
Use cases
Use multiple selection
The SelectV2
supports multiple selection. You can enable that by adding the
multiple
prop.
Group options together
You can use the SelectV2.Groups
to group more options in the same group.
Control the state
The SelectV2
can also be controlled, meaning that you can handle the selection
state. To do so, you need to use the onChange
prop to provide a handler that
is called when the internal state changes. That state can be modified and is
applied as soon as it's passed to the value
prop.
Show a custom placeholder
You can use the SelectV2.Trigger
component to show a placeholder for the
trigger button by adding the placeholder
prop. If no option is selected, the
placeholder
value is shown by default. Notice that the clearable
prop is
used here to enable empty selection.
Show a custom display value
You can use the SelectV2.DisplayValue
component to customize what is rendered
on the trigger. By default, the placeholder is shown when no option is selected.
You can also render content inside a SelectV2.Prefix
component to show an icon
in front of the trigger display value for example. When you select a value, the
content inside the SelectV2.DisplayValue
slot is then rendered inside the
trigger.
Customize the trigger
You can use the SelectV2.CustomTrigger
component to render custom content
inside the trigger slot, so you can control the styling or its rendered text.
As the SelectV2
component renders a hidden input inside the trigger for forms
integration, if you're using an interactive element (e.g. a <button>
) as
trigger, you would run into accessibility issues due to nesting interactive
items. Therefore, you would need to polymorph it to a non-interactive element
(e.g. a <div>
) and take care of the focus styling yourself. To do so, you can
use the useFocusRing
utility and pass it the focusWithin
option, which
returns the necessary focus styles if an embedded element gains the focus. See
the useFocusRing documentation
for more details.
Disable options
In the SelectV2
, you can disable each option separately by adding the
disabled
prop on the SelectV2.Option
component. Otherwise, if you need to
disable the whole SelectV2
component, you can add the disabled
prop
directly.
Filter options
You can search through options by adding the SelectV2.Filter
component. This
renders a search input, where you can type the filtering term and filter the
options on the client-side. If no options are found after filtering, you can
also customize the shown message by adding content to the SelectV2.EmptyState
component, which is only valid within the SelectV2.Content
element. Otherwise,
the default message is shown: "No items found.".
Control the filtering of the options
You can also control the filtering of the options by adding the value
and the
onFilterChange
props on the SelectV2.Filter
component.
Filter complex options
If you're using a custom component as SelectV2.Option
, the text value of this
option can't be determined automatically. To enable the filtering of these
options and to show which option is selected, you need to provide a textValue
with a string representation of the SelectV2.Option
.
Add icons to options
The SelectV2.SelectOption
component allows adding icons in front of the option
node with the SelectV2.Prefix
or after it with the SelectV2.Suffix
. The same
can be done to add prefix and suffix icons inside the SelectV2.DisplayValue
slot, as shown
above.
Show the loading state
You can show the loading state of the SelectV2.Option
components by adding the
loading
prop to the SelectV2.Content
component.
Set the width of the trigger
You can set the width of the trigger by adding the width
prop on the
SelectV2.Trigger
component and either giving it a fixed value or setting it to
full
, which would adjust it to the width of its container. By default, it's
set to content
, so it adjusts to the width of the trigger content.
Set the width of the content
You can set the width of the content by adding the width
prop on the
SelectV2.Content
component and giving it a fixed value. By default, it has a
min-width of 96px and adjusts to the size of the trigger. If the text of the
options is overflowing, the text is truncated at the end by default. However,
you can also add the TextEllipsis
component directly inside the
SelectV2.Option
and wrap the text inside it to set the truncation to the start
or middle, if necessary. See
the TextEllipsis documentation
for more details.
Pass large amounts of data
The SelectV2
can handle large amounts of options. If the content is too large
to fit, the select options are virtualized.
Show selected options first
In the SelectV2
, you can use the showSelectedOptionsFirst
prop to configure
whether the options should be reordered to show the selected options at the top.
If this is set to true
the options will be reordered when the overlay is
closed and opened again. For elected options inside an SelectV2.Group
, this
will position its group at the top, as well as order the option to the top
within the group.
Validate
This example shows how you can validate the SelectV2
using the
react-hook-form
package, which handles error messages. For connecting the form
with the SelectV2
and validating, you need to register the field with custom
error messages and use the useForm
hook from react-hook-form
. Also, by using
the controlState
prop, you can override the error messages and connect the
SelectV2
's error state and message to that of the form. This shows a hint in
case of an error and applies proper styling to the component. You can also add
custom validation logic when registering the SelectV2
by passing in a
validate
function to the register
options.
React to open state changes
In the SelectV2
you can react to changes to the open state using the
onOpenChange
prop. This prop expects a callback method which receives the new
open state as a single boolean
argument.
Props
SelectV2Props
Signature:
export declare type SelectV2Props<, extends > = <, > & (<, > | <, >) & & & & ;
_SelectV2BaseProps
Signature:
export declare type _SelectV2BaseProps<T, extends > = <{
/**
* Used to compare options with objects for values either by a specified property of the object or through a comparator function.
*/
compareBy?: keyof T | ((valueA: T, valueB: T) => );
/** Name used for the component when submitting it in a form */
name?: ;
/** Form name used to connect the component to a form */
form?: ;
/**
* Boolean to determine whether the component is required
*
* @defaultValue false
*/
required?: ;
/**
* Whether the component is disabled
*
* @defaultValue false
*/
disabled?: ;
/**
* Event handler called when the open state for the select changes
*/
onOpenChange?: (isOpen: ) => ;
/**
* Whether or not the select allows multiple selection or not
* @defaultValue false
*/
multiple?: ;
/**
* Whether or not the select is clearable.
* @defaultValue false for single select, true for multi select
*/
clearable?: ;
/** Callback that is called when the select trigger loses focus. */
onBlur?: (e: <, >) => ;
/** Callback that is called when the select trigger gets focus. */
onFocus?: (e: <, >) => ;
}>;
SelectValueControlledProps
Name | Type | Default | Description |
---|---|---|---|
value | extends true ? <> : <> | - | |
onChange | (value: <, >) => | - |
SelectValueUncontrolledProps
Name | Type | Default | Description |
---|---|---|---|
defaultValue? | extends true ? <> : <> | - |
SelectV2 base components
SelectV2.Content
The SelectV2.Content
wraps all the custom content of the overlay, including
the options, groups, and group labels.
SelectV2ContentProps
Signature:
export declare type SelectV2ContentProps = <> & & & {
/**
* The current loading state of the Select.Content. If true, a loading icon is shown.
* @defaultValue false
*/
loading?: ;
/**
* The width of the SelectV2.Content (overlay). By default it has a min-width of 96px and adjusts to the size of the trigger.
* @defaultValue
*/
width?: ;
/**
* Whether the selected options are reordered to the top of the options.
* @defaultValue false
*/
showSelectedOptionsFirst?: ;
};
SelectV2.Prefix
The SelectV2.Prefix
component can only be used inside the
SelectV2.DisplayValue
component or the SelectV2.Option
component.
SelectV2PrefixProps
Signature:
export declare type SelectV2PrefixProps = <> & & ;
SelectV2.Suffix
The SelectV2.Suffix
component can only be used inside the
SelectV2.DisplayValue
component or the SelectV2.Option
component.
SelectV2SuffixProps
Signature:
export declare type SelectV2SuffixProps = <> & & ;
SelectV2 overlay components
SelectV2.Option
Every option of the select is represented by the children of the
SelectV2.Option
component.
SelectV2OptionProps
Signature:
export declare type SelectV2OptionProps<> = & & & {
value: ;
textValue?: ;
id?: ;
?: ;
disabled?: ;
};
SelectV2.Group
The SelectV2.Group
component can be used to add groups to the SelectV2
component.
SelectV2GroupProps
Signature:
export declare type SelectV2GroupProps = <> & & ;
SelectV2.GroupLabel
When using groups inside the SelectV2
component, you can name each group by
adding a SelectV2.GroupLabel
component with a suitable title.
SelectV2GroupLabelProps
Signature:
export declare type SelectV2GroupLabelProps = <> & & ;
SelectV2.Filter
SelectV2FilterProps
Signature:
export declare type SelectV2FilterProps = & {
/**
* Flag indicating if the client-side filtering should be disabled or not.
* @defaultValue false
**/
disableFiltering?: ;
/** Defines the default filter . */
defaultValue?: ;
/** Defines the filter value. */
value?: ;
/** The callback is triggered when the filterValue changes. */
onChange?: (filterValue: ) => ;
};
SelectV2.EmptyState
SelectV2EmptyStateProps
Signature:
export declare type SelectV2EmptyStateProps = <> & ;
SelectV2 trigger components
SelectV2.Trigger
The SelectV2.Trigger
component is used to render the trigger that opens or
closes the overlay.
SelectV2TriggerProps
Signature:
export declare type SelectV2TriggerProps = & & & {
/**
* The placeholder text displayed in the SelectV2.Trigger.
*/
placeholder?: ;
/**
* The width of the SelectV2.Trigger.
* @defaultValue
*/
width?: ;
};
SelectV2.DisplayValue
SelectV2DisplayValueProps
Signature:
export declare type SelectV2DisplayValueProps = <>;
SelectV2.CustomTrigger
SelectV2CustomTriggerProps
Signature:
export declare type SelectV2CustomTriggerProps = ;