Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(select): Adds documentation to React examples. #9536

Merged
merged 9 commits into from
Nov 21, 2023
57 changes: 48 additions & 9 deletions packages/react-core/src/components/Select/examples/Select.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,47 +13,78 @@ import BellIcon from '@patternfly/react-icons/dist/esm/icons/bell-icon';

## Examples

`Select` builds off of the Menu component suite to wrap commonly used properties and functions for a select menu. See the [Menu documentation](/components/menus/menu) for a full list of properties that may be passed through `Select` to further customize the select menu, or the [custom menu examples](/components/menus/custom-menus) for additional examples of fully functional menus.
Select builds off of the menu component suite to adapt commonly used properties and functions to create a select menu. See the [menu documentation](/components/menus/menu) for a full list of properties that may be used to further customize a select menu. View the [custom menu examples](/components/menus/custom-menus) to see examples of fully functional select menus.

### Single
### Single select
To let users select a single item from a list, use a single select menu.

You can add multiple `<SelectOption>` components to build out a list of menu items. For each select option, pass a relevant option label to the `value` property.

To prevent a toggle click from opening a select list, use the `isDisabled` property. In the following example, select the checkbox to observe this behavior.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="./SelectBasic.tsx"

```

### Option variations
### Select option variants

The following example showcases different option variants and customizations that are commonly used in a select menu.

To create these variants, you can pass different properties into a `<SelectOption>` component.

Showcases different option variants and customizations that are commonly used in a select menu. For a more complete list, see the [Menu documentation](/components/menus/menu).
This example provides examples of:

- An option with a description, which is created by using the `description` property.
- An option with a link, which is created by passing a URL into the `to` property. For external links, use the `isExternalLink` property so that the option is styled with an outbound link icon.
- An option with an icon, which is created by using the `icon` property.
- An option that is disabled by using the `isDisabled` property.

```ts file="./SelectOptionVariations.tsx"

```

### Grouped single
### With grouped items
To group related select options together, use 1 or more `<SelectGroup>` components and title each group using the `label` property.

```ts file="./SelectGrouped.tsx"

```

### Checkbox
### Checkbox select
To let users select multiple list options via checkbox input, use a checkbox select.

To create a checkbox select, pass `hasCheckbox` into each `<SelectOption>` component. To indicate that an option is selected, use the `isSelected` property.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

By default, the menu toggle will display a badge to indicate the number of items that a user has selected.

```ts file="./SelectCheckbox.tsx"

```

### Typeahead
Typeahead is a select variant that replaces the typical button toggle for opening the select menu with a text input and button toggle combo. As a user enters characters into the text input, the select menu will provide suggestions by filtering the select options.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

To make a typeahead, pass `variant=typeahead` into the `<MenuToggle>` component and link an `onClick` function to the `<TextInputGroupMain>` component.

```ts file="./SelectTypeahead.tsx"

```

### Typeahead with create option
If a user enters a value into a typeahead select menu that does not exist, you can allow them to create an option of that value.

To enable the creation ability, pass `value='create'` into a `<SelectOption>` component. Additionally, you should pass a button with an `onClick` event into the `<TextInputGroupUtilities>` component to display the creation prompt after a user enters a new value. You can use the `placeholder` property to change the default text shown in the text input.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

The following example outlines the code implementation required to create a working typeahead menu that allows for creation.

```ts file="./SelectTypeaheadCreatable.tsx"

```

### Multiple typeahead with chips
A multiple typeahead can be used to allow users to select multiple options from a list. Selected items appear as chips in the select toggle.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

When more items than the allowed limit are selected, overflowing items will be hidden under a "more" button. The following example hides items after more than 3 are selected. To show hidden items, select the “more” button. Select "show less" to hide extra items again.

```ts file="./SelectMultiTypeahead.tsx"

Expand All @@ -66,19 +97,27 @@ Showcases different option variants and customizations that are commonly used in
```

### Multiple typeahead with checkboxes
By default, a multiple typeahead select allows you to select multiple menu items, placing a checkmark beside selected items. Like basic checkbox select menus, you can add checkboxes to your menu items. This approach may be more accurate and comprehensive for menu scenarios, like filtering.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="./SelectMultiTypeaheadCheckbox.tsx"

```

### View more
### With view more

To reduce the processing load for long select lists, replace overflow items with a "View more" link at the bottom of the select menu.

You can adjust the number of items shown above the "View more" link as needed. The following example passes 3 items into this property.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="./SelectViewMore.tsx"

```

### Footer
### With a footer

You can add a `<MenuFooter>` component to a select menu to hold additional actions that users can take on menu items, through elements such as link buttons. A footer will be placed beneath a divider at the end of the select menu.


```ts file="./SelectFooter.tsx"

```
```
Loading