Super select
EuiSuperSelect is a flexible alternative to EuiSelect that lets you customize the input and option displays. Provide an array of option objects with:
value: a unique value for each item,inputDisplay: what appears in the input when selected,dropdownDisplay: (optional) custom React nodes for multi-line option text or descriptions.
The component creates a select-style button that opens a popover with selectable items.
For more details on which selection component to use, see the Component comparison.
Wrap your form controls in a form row
Use the EuiFormRow component to easily and accessibly associate form components with labels, help text, and error text.
More complex
Both inputDisplay and dropdownDisplay accept React nodes. Therefore you can pass some descriptions with each option to show in the dropdown. If your options will most likely be multi-line, add the hasDividers prop to show borders between options.
A placeholder prop may also be passed that accepts string as well as React nodes (to match your inputDisplay if necessary). This placeholder will only show when valueOfSelected is empty.
States
You can pass the same props as you normally would to EuiSelect like disabled, isLoading, compressed, etc.
Usage
Labels
Avoid long labels, but don't sacrifice clarity. If needed, put additional information in help text and tooltips.
Do: Say what the field is in the label. Use help text for additional information.
Don't: Put everything in the label. It's hard to scan.
Hint text
Place hints and instructions outside a text field so it is always visible to the user. Keep the hint text short, maximum two sentences long. Use hint text to:
- Explain why you are asking a certain question: "We will only email you if there is a problem with your order."
- Provide clarifying details on what to type: "Enter the full 32-character ID."
- Tell the user where to find the information you're asking for: "Find the Elasticsearch cluster ID on the main administration page of your deployment."
Do: Help users make the right decision by clarifying what goes inside a field.
Do: Use complete sentences and ending punctuation.
Placeholder text
In fields
Use the placeholder property to describe the expected value of the input or to provide a useful example.
Do: Provide a simple example that highlights the expected syntax or value.
Don't: Start with `for example`, or `e.g.`.
Add placeholder text in addition to field labels and help text, not as a replacement. Omit it if it doesn't add value for users. And keep it short.
Do: Place info essential to completing the form outside the field so that it is always visible.
Don't: Use text that adds no value, such as “Type here”.
Do: When space is limited and the UI is very simple, you can use field labels as placeholder text. This must stay an exception.
Do: If space allows it, prefer following the rule described earlier with labels outside of the fields.
In search bars
In a search bar, be specific about what users can enter.
Do: Give users a hint at things they might want to search for. State the action the user performs (find, search) instead of the field functionality (jump to).
Don't: Use an ellipsis.
Props
EuiSuperSelect
Prop | Description and type | Default value |
|---|---|---|
Prop options# | Description and type Pass an array of options that must at least include: EuiSuperSelectOption<T>[] | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Type: string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop append# | Description and type Creates an input group with element(s) coming after input. PrependAppendType | Default value |
Prop prepend# | Description and type Creates an input group with element(s) coming before input. PrependAppendType | Default value |
Prop name# | Description and type Type: string | Default value |
Prop fullWidth# | Description and type Expand to fill 100% of the parent. boolean | Default value false |
Prop isLoading# | Description and type Type: boolean | Default value false |
Prop buttonRef# | Description and type Type: Ref<HTMLButtonElement> | Default value |
Prop readOnly# | Description and type Type: boolean | Default value |
Prop compressed# | Description and type Type: boolean | Default value false |
Prop placeholder# | Description and type Placeholder to display when the current selected value is empty. ReactNode | Default value |
Prop isInvalid# | Description and type Type: boolean | Default value false |
Prop valueOfSelected# | Description and type Type: {} | Default value |
Prop itemClassName# | Description and type Classes for the context menu item string | Default value |
Prop onChange# | Description and type You must pass an (value: T) => void | Default value |
Prop onFocus# | Description and type Type: (event?: FocusEvent<Element, Element>) => void | Default value |
Prop onBlur# | Description and type Type: (event?: FocusEvent<Element, Element>) => void | Default value |
Prop hasDividers# | Description and type Change to boolean | Default value false |
Prop itemLayoutAlign# | Description and type Change EuiContextMenuItemLayoutAlignment | Default value |
Prop isOpen# | Description and type Controls whether the options are shown. Default: false boolean | Default value |
Prop popoverProps# | Description and type Optional props to pass to the underlying EuiInputPopover. Does not accept a nested Partial<CommonProps & Omit<EuiInputPopoverProps, "isOpen">> | Default value |