diff --git a/docs/components/select.md b/docs/components/select.md index 79ab2ddf8..3badbc8b8 100644 --- a/docs/components/select.md +++ b/docs/components/select.md @@ -3,35 +3,432 @@ [component-header:sl-select] ```html preview -
- - Option 1 - Option 2 - Option 3 - Option 4 - Option 5 - Option 6 - - -
- - - Option 1 - Option 2 - Option 3 - Option 4 - Option 5 - Option 6 - - -
- - Submit -
- - + + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + Option 6 + ``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + Option 6 + +); +``` + +?> This component works with standard `
` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation. + +## Examples + +### Labels + +Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Help Text + +Add descriptive help text to a select with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead. + +```html preview + + Novice + Intermediate + Advanced + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Novice + Intermediate + Advanced + +); +``` + +### Placeholders + +Use the `placeholder` attribute to add a placeholder. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Clearable + +Use the `clearable` attribute to make the control clearable. The clear button only appears when an option is selected. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Filled Selects + +Add the `filled` attribute to draw a filled select. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Pill + +Use the `pill` attribute to give selects rounded edges. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Disabled + +Use the `disabled` attribute to disable a select. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Multiple + +To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. To set multiple values at once, set `value` to a space-delimited list of values. + +```html preview + + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + Option 6 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + Option 6 + +); +``` + +?> Note that multi-select options may wrap, causing the control to expand vertically. You can use the `max-options-visible` attribute to control the maximum number of selected options to show at once. + +### Setting Initial Values + +Use the `value` attribute to set the initial selection. When using `multiple`, use space-delimited values to select more than one option. + +```html preview + + Option 1 + Option 2 + Option 3 + Option 4 + +``` + +```jsx react +import { SlDivider, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Grouping Options + +Use `` to group listbox items visually. You can also use `` to provide labels, but they won't be announced by most assistive devices. + +```html preview + + Section 1 + Option 1 + Option 2 + Option 3 + + Section 2 + Option 4 + Option 5 + Option 6 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + Option 6 + +); +``` + +### Sizes + +Use the `size` attribute to change a select's size. Note that size does not apply to listbox options. + +```html preview + + Option 1 + Option 2 + Option 3 + + +
+ + + Option 1 + Option 2 + Option 3 + + +
+ + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + Option 1 + Option 2 + Option 3 + + +
+ + + Option 1 + Option 2 + Option 3 + + +
+ + + Option 1 + Option 2 + Option 3 + + +); +``` + +### Placement + +The preferred placement of the select's listbox can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are `top` and `bottom`. + +```html preview + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { + SlOption, + SlSelect +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + +); +``` + +### Prefix Icons + +Use the `prefix` slot to add an icon. + +```html preview + + + Option 1 + Option 2 + Option 3 + +
+ + + Option 1 + Option 2 + Option 3 + +
+ + + Option 1 + Option 2 + Option 3 + +``` + +```jsx react +import { SlIcon, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + Option 1 + Option 2 + Option 3 + +
+ + + Option 1 + Option 2 + Option 3 + +
+ + + Option 1 + Option 2 + Option 3 + + +); +``` + +[component-metadata:sl-select] diff --git a/docs/getting-started/form-controls.md b/docs/getting-started/form-controls.md index 94a683331..73aff208f 100644 --- a/docs/getting-started/form-controls.md +++ b/docs/getting-started/form-controls.md @@ -322,7 +322,7 @@ This example demonstrates custom validation styles using `data-user-invalid` and /* user invalid styles */ .validity-styles sl-input[data-user-invalid]::part(base), - .validity-styles sl-select[data-user-invalid]::part(control) { + .validity-styles sl-select[data-user-invalid]::part(combobox) { border-color: var(--sl-color-danger-600); } @@ -332,14 +332,14 @@ This example demonstrates custom validation styles using `data-user-invalid` and } .validity-styles sl-input:focus-within[data-user-invalid]::part(base), - .validity-styles sl-select:focus-within[data-user-invalid]::part(control) { + .validity-styles sl-select:focus-within[data-user-invalid]::part(combobox) { border-color: var(--sl-color-danger-600); box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-300); } /* User valid styles */ .validity-styles sl-input[data-user-valid]::part(base), - .validity-styles sl-select[data-user-valid]::part(control) { + .validity-styles sl-select[data-user-valid]::part(combobox) { border-color: var(--sl-color-success-600); } @@ -349,7 +349,7 @@ This example demonstrates custom validation styles using `data-user-invalid` and } .validity-styles sl-input:focus-within[data-user-valid]::part(base), - .validity-styles sl-select:focus-within[data-user-valid]::part(control) { + .validity-styles sl-select:focus-within[data-user-valid]::part(combobox) { border-color: var(--sl-color-success-600); box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300); }