From 0a05949d3ac5057069e88120741e0ba807056894 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Tue, 15 Nov 2022 14:16:06 -0600 Subject: [PATCH 01/10] rearranging, first pass on autocomplete --- docs/data/joy/components/alert/AlertColors.js | 2 +- .../data/joy/components/alert/AlertColors.tsx | 2 +- docs/data/joy/components/alert/alert.md | 42 +++--- .../components/aspect-ratio/aspect-ratio.md | 66 +++------ .../components/autocomplete/autocomplete.md | 125 ++++++++++++------ docs/data/joy/components/avatar/avatar.md | 24 ++-- 6 files changed, 137 insertions(+), 124 deletions(-) diff --git a/docs/data/joy/components/alert/AlertColors.js b/docs/data/joy/components/alert/AlertColors.js index 42d37cc6db85a7..3b0fe7392edf47 100644 --- a/docs/data/joy/components/alert/AlertColors.js +++ b/docs/data/joy/components/alert/AlertColors.js @@ -20,7 +20,7 @@ export default function AlertColors() { diff --git a/docs/data/joy/components/alert/AlertColors.tsx b/docs/data/joy/components/alert/AlertColors.tsx index 6faf248a6b43ec..294b9b5c75864a 100644 --- a/docs/data/joy/components/alert/AlertColors.tsx +++ b/docs/data/joy/components/alert/AlertColors.tsx @@ -20,7 +20,7 @@ export default function AlertColors() { diff --git a/docs/data/joy/components/alert/alert.md b/docs/data/joy/components/alert/alert.md index 333f6ac7416dcf..6edd6ecf72286a 100644 --- a/docs/data/joy/components/alert/alert.md +++ b/docs/data/joy/components/alert/alert.md @@ -40,38 +40,18 @@ The Alert component wraps around its content, and stretches to fill its enclosin {{"demo": "AlertBasic.js"}} -## Anatomy - -The Alert component is composed of a single root `
` element with its `role` set to `alert`: - -```html - -``` - -### Overriding the root slot - -Use the `component` prop to override the root slot with a custom element. -For example, the following code snippet replaces the default `
` with a ``: - -```jsx -Alert content - -// renders as: - - Alert content - -``` - ## Customization ### Variants -The Alert component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`. +The Alert component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. {{"demo": "AlertVariants.js"}} +:::success +To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +::: + ### Colors Every palette included in the theme is available via the `color` prop. @@ -81,7 +61,7 @@ The demo below shows how the values for the `color` prop are affected by the glo ### Sizes -The Alert component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`: +The Alert component comes in three sizes: `sm`, `md` (default), and `lg`: {{"demo": "AlertSizes.js"}} @@ -111,3 +91,13 @@ Here are some factors to consider to ensure that your Alert is accessible: - Alerts that occur too frequently can [inhibit the usability](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-postponed.html) of your app. - Dynamically rendered alerts are announced by screen readers; alerts that are already present on the page when it loads are _not_ announced. - Color does not add meaning to the UI for users who require assistive technology. You must ensure that any information conveyed through color is also denoted in other ways, such as within the text of the alert itself, or with additional hidden text that's read by screen readers. + +## Anatomy + +The Alert component is composed of a single root `
` element with its `role` set to `alert`: + +```html + +``` diff --git a/docs/data/joy/components/aspect-ratio/aspect-ratio.md b/docs/data/joy/components/aspect-ratio/aspect-ratio.md index bb6b4d694d8dbc..175094cc0c2252 100644 --- a/docs/data/joy/components/aspect-ratio/aspect-ratio.md +++ b/docs/data/joy/components/aspect-ratio/aspect-ratio.md @@ -38,56 +38,18 @@ The default ratio is `16/9`. {{"demo": "BasicRatio.js"}} -## Anatomy - -The Aspect Ratio component is composed of a root `
` with a content `
` nested inside; the child component is given a `data-first-child` attribute for styling purposes: - -```html -
-
- - This is how an Aspect Ratio component renders in the DOM. - -
-
-``` - -### Overriding the root slot - -Use the `component` prop to override the root slot with a custom element. -For example, the following code snippet replaces the default `
` with a `
`: - -```jsx - -``` - -### Overriding interior slots - -Use the `components` prop to override any interior slots in addition to the root: - - - -:::warning -If the root element is customized with both the `component` and `components` props, then `component` will take precedence. -::: - -Use the `componentsProps` prop to pass custom props to internal slots. -The following code snippet applies a CSS class called `my-content` to the content slot: - - - -:::warning -Note that `componentsProps` slot names are written in lowercase (root) while `components` slot names are capitalized (Root). -::: - ## Customization ### Variants -The Aspect Ratio component supports the four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. +The Aspect Ratio component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. {{"demo": "VariantsRatio.js"}} +:::success +To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +::: + ### Ratio Use the `ratio` prop to change the aspect ratio, following the pattern `height/width`. @@ -120,13 +82,13 @@ This is useful when the Aspect Ratio component wraps dynamic-width content, as s {{"demo": "MinMaxRatio.js"}} -### Usage inside a flex row +## Usage inside a flex row When the Aspect Ratio component is a child of a flexbox `row` container, use `flex-basis` to set the ideal width of the content: {{"demo": "FlexRowRatio.js"}} -### Usage with Next.js Image component +## Usage with Next.js Image component The Aspect Ratio component can be used with a [Next.js Image](https://nextjs.org/docs/basic-features/image-optimization) component as a child. The Image should always include the `layout="fill"` property—otherwise it requires `height` and `width` values, which would defeat the purpose of the Aspect Ratio component. @@ -161,3 +123,17 @@ In designs like this, make sure to assign a `minWidth` value to prevent the Aspe This is a simple illustration of how to use Aspect Ratio with list components: {{"demo": "ListStackRatio.js"}} + +## Anatomy + +The Aspect Ratio component is composed of a root `
` with a content `
` nested inside; the child component is given a `data-first-child` attribute for styling purposes: + +```html +
+
+ + + +
+
+``` diff --git a/docs/data/joy/components/autocomplete/autocomplete.md b/docs/data/joy/components/autocomplete/autocomplete.md index b93886027ff96a..ac23aa7e0d675e 100644 --- a/docs/data/joy/components/autocomplete/autocomplete.md +++ b/docs/data/joy/components/autocomplete/autocomplete.md @@ -7,11 +7,12 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ # Autocomplete -

The autocomplete is a text input enhanced by a panel of suggested options when users start typing.

+

The Autocomplete component is a text input enhanced by a panel of suggested options when users start typing.

## Introduction -`Autocomplete` is an enhanced version of text input that shows suggested options as the users type and also let them select an option from the list. +The Autocomplete component is an enhanced version of a text input that shows suggested options as a user types, and lets them select options from the list. +It includes many sophisticated customization options to suit a wide range of design and user experience needs. {{"demo": "Playground.js", "hideToolbar": true}} @@ -32,26 +33,30 @@ export default function App() { ## Basics -The Autocomplete component requires a list of `options` to be displayed after the textbox is focused. The value must be chosen from a predefined set of allowed values. - -{{"demo": "BasicAutocomplete.js"}} - -## Customization - -### Options structure - -By default, the `options` accepts an array of `string` or `{ label: string }`: +The Autocomplete component requires a list of options, which is displayed when the input receives focus. +The user must choose from this predefined set of values passed to the `options` prop. +This prop accepts either an array of strings, or an array of objects with the desired values assigned to the `label` key, as shown below: ```js +// options can be an array of strings... +const options = ['The Godfather', 'Pulp Fiction']; + +// ...or an array of objects (using the label key) const options = [ { label: 'The Godfather', id: 1 }, { label: 'Pulp Fiction', id: 2 }, ]; -// or -const options = ['The Godfather', 'Pulp Fiction']; + ``` -However, you can use different structures by providing a `getOptionLabel` prop: +{{"demo": "BasicAutocomplete.js"}} + +## Customization + +### Custom option labels + +Use the `getOptionLabel` prop to populate the Autocomplete component with values assigned to a different key than `label`. +For example, the code snippet below populates the Autocomplete with values from the `title` key instead: ```js const options = [ @@ -64,13 +69,13 @@ const options = [ ### Option appearance -To customize the appearance of the options, use `renderOption` prop in combination with the `AutocompleteOption` component as an option container. +To customize the appearance of the options, use the `renderOption` prop along with the Autocomplete Option component as an option container. {{"demo": "CountrySelect.js"}} ### Variants -The autocomplete component supports the four global variants: `outlined` (default), `soft`, `solid`, and `plain`. +The Autocomplete component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft`, `outlined` (default), and `plain`. {{"demo": "InputAppearance.js"}} @@ -80,7 +85,7 @@ To learn how to add more variants to the component, check out [Themed components ### Label -Put an `Autocomplete`, a `FormLabel` and a `FormHelperText` (optional) under a `FormControl` component to create an accessible autocomplete. +Put an Autocomplete, a Form Label, and a Form Helper Text (optional) under a Form Control component to create an accessible Autocomplete: {{"demo": "LabelAndHelperText.js"}} @@ -98,7 +103,7 @@ The component has two states that can be controlled: 2. the "input value" state with the `inputValue`/`onInputChange` props combination. This state represents the value displayed in the textbox. :::warning -⚠️ These two states are isolated, they should be controlled independently. +⚠️ These two states are isolated, and should be controlled independently. ::: {{"demo": "ControllableStates.js"}} @@ -125,7 +130,7 @@ It displays a progress state as long as the network request is pending. ### Search input -Use `freeSolo` to create a **search input** with suggestions experience, e.g. Google search or [react-autowhatever](https://github.com/moroshko/react-autowhatever). +Use `freeSolo` to create a search input with suggestions, similar to Google search or [react-autowhatever](https://github.com/moroshko/react-autowhatever). {{"demo": "FreeSolo.js"}} @@ -135,9 +140,9 @@ Use `freeSolo` to create a **search input** with suggestions experience, e.g. Go The value created by typing into the textbox is always a string, regardless of the type of the options. ::: -### User's created option +### User-created option -If you intend to use `freeSolo` mode for a [combo box](#combo-box) like experience (an enhanced version of a select element) we recommend setting: +If you intend to use `freeSolo` mode for a [combo box](#combo-box)-like experience (an enhanced version of a select element), try using: - `selectOnFocus` to help the user clear the selected value. - `clearOnBlur` to help the user enter a new value. @@ -146,25 +151,25 @@ If you intend to use `freeSolo` mode for a [combo box](#combo-box) like experien {{"demo": "FreeSoloCreateOption.js"}} -You could also display a dialog when the user wants to add a new value. +You could also display a dialog when the user wants to add a new value: {{"demo": "FreeSoloCreateOptionDialog.js"}} :::info -The `AutocompleteOption` uses the same styles and variables as [`ListItemButton`](/joy-ui/react-list/#actionable), so that you get the same customization experience. +The Autocomplete Option component uses the same styles and variables as [List Item Button](/joy-ui/react-list/#actionable), so that you get the same customization experience. ::: ### Validation -To display invalid state, set the `error` prop on the `FormControl`. +To display an invalid state, set the `error` prop on the Form Control. {{"demo": "AutocompleteError.js"}} ### Multiple selection -By default, the autocomplete uses [`Chip`](/joy-ui/react-chip/) component to render the user's selected options. +By default, Autocomplete uses the [Chip](/joy-ui/react-chip/) component to render the user's selected options. -When the autocomplete is focused, the user can press the backspace to remove the latest selected option from the list. +When the Autocomplete is focused, the user can press the backspace to remove the latest selected option from the list. {{"demo": "Tags.js"}} @@ -182,7 +187,7 @@ You can use the `limitTags` prop to limit the number of displayed options when n ### Sizes -The autocomplete component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`. The size is propagated to internal components, including `Input`, `Chip`, and `List`. +The Autocomplete component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`. The size is propagated to internal components, including `Input`, `Chip`, and `List`. {{"demo": "Sizes.js"}} @@ -190,7 +195,7 @@ The autocomplete component comes with three sizes out of the box: `sm`, `md` (th To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). ::: -The `size` can also be controlled at the `FormControl`. +The `size` can also be controlled at the Form Control. {{"demo": "SizeWithLabel.js"}} @@ -233,7 +238,7 @@ const filterOptions = createFilterOptions({ ### Advanced filter -For richer filtering mechanisms, like fuzzy matching, it's recommended to look at [match-sorter](https://github.com/kentcdodds/match-sorter). For instance: +For richer filtering mechanisms, like fuzzy matching, try using [match-sorter](https://github.com/kentcdodds/match-sorter) as a reference point. For instance: ```jsx import { matchSorter } from 'match-sorter'; @@ -251,21 +256,23 @@ The following demo relies on [autosuggest-highlight](https://github.com/moroshko {{"demo": "Highlights.js"}} -### GitHub's picker +### GitHub label picker -To reproduce GitHub's label picker, the `Autocomplete` is rendered inside a [`PopperUnstyled`](/base/react-popper/). To remove the popup behavior from the autocomplete, replace the listbox slot with the `AutocompleteListbox` component. +To reproduce GitHub's label picker, the Autocomplete is rendered inside an [Unstyled Popper](/base/react-popper/). +To remove the popup behavior from the autocomplete, replace the listbox slot with the Autocomplete Listbox component. {{"demo": "GitHubLabel.js"}} ### Virtualization -Search within 10,000 randomly generated options. The list is virtualized thanks to [react-window](https://github.com/bvaughn/react-window). +Search within 10,000 randomly-generated options. +The list is virtualized thanks to [react-window](https://github.com/bvaughn/react-window). {{"demo": "Virtualize.js"}} ## Events -If you would like to prevent the default key handler behavior, you can set the event's `defaultMuiPrevented` property to `true`: +To prevent the default key handler behavior, you can set the event's `defaultMuiPrevented` property to `true`: ```jsx ` and a ` +
+``` diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index efb136b051115c..07995bcd887c8a 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -33,16 +33,6 @@ export default function MyApp() { By default, the Avatar component displays a generic Person Icon. Wrap it around a string to display plain text, or use the `src` prop to display an image. -## Anatomy - -The Avatar component is composed of a root `
` that may wrap around an ``, an ``, or a string: - -```html -
- -
-``` - ## Customization ### Text Avatar @@ -71,7 +61,7 @@ If an error occurs while loading the Avatar's image, it will fall back to the fo ### Variants -The Avatar component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`. +The Avatar component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. {{"demo": "AvatarVariants.js"}} @@ -81,7 +71,7 @@ To learn how to add more variants to the component, check out [Themed components ### Sizes -The Avatar component comes in three sizes: `sm`, `md` (the default), and `lg`: +The Avatar component comes in three sizes: `sm`, `md` (default), and `lg`: {{"demo": "AvatarSizes.js"}} @@ -147,3 +137,13 @@ Play around with the CSS variables available to the Avatar component to see how You can use these to customize the component with both the `sx` prop and the theme. {{"demo": "AvatarGroupVariables.js", "hideToolbar": true }} + +## Anatomy + +The Avatar component is composed of a root `
` that may wrap around an ``, an ``, or a string: + +```html +
+ +
+``` From ca0f38362beb9697bb6198f2e685816c0bbba936 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Tue, 15 Nov 2022 14:26:20 -0600 Subject: [PATCH 02/10] more rearranging --- docs/data/joy/components/alert/alert.md | 3 ++- docs/data/joy/components/aspect-ratio/aspect-ratio.md | 3 ++- docs/data/joy/components/autocomplete/autocomplete.md | 5 +++-- docs/data/joy/components/avatar/avatar.md | 3 ++- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/data/joy/components/alert/alert.md b/docs/data/joy/components/alert/alert.md index 6edd6ecf72286a..a6299122f0d6f0 100644 --- a/docs/data/joy/components/alert/alert.md +++ b/docs/data/joy/components/alert/alert.md @@ -49,7 +49,8 @@ The Alert component supports Joy UI's four [global variants](/joy-ui/main-featur {{"demo": "AlertVariants.js"}} :::success -To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +Note that you lose the global variants when you add custom variants. ::: ### Colors diff --git a/docs/data/joy/components/aspect-ratio/aspect-ratio.md b/docs/data/joy/components/aspect-ratio/aspect-ratio.md index 175094cc0c2252..d1a4dffca44f7f 100644 --- a/docs/data/joy/components/aspect-ratio/aspect-ratio.md +++ b/docs/data/joy/components/aspect-ratio/aspect-ratio.md @@ -47,7 +47,8 @@ The Aspect Ratio component supports Joy UI's four [global variants](/joy-ui/main {{"demo": "VariantsRatio.js"}} :::success -To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +Note that you lose the global variants when you add custom variants. ::: ### Ratio diff --git a/docs/data/joy/components/autocomplete/autocomplete.md b/docs/data/joy/components/autocomplete/autocomplete.md index ac23aa7e0d675e..320e835e6c0973 100644 --- a/docs/data/joy/components/autocomplete/autocomplete.md +++ b/docs/data/joy/components/autocomplete/autocomplete.md @@ -33,7 +33,7 @@ export default function App() { ## Basics -The Autocomplete component requires a list of options, which is displayed when the input receives focus. +The Autocomplete component requires a list of options, which is displayed when the input receives focus or the button is clicked. The user must choose from this predefined set of values passed to the `options` prop. This prop accepts either an array of strings, or an array of objects with the desired values assigned to the `label` key, as shown below: @@ -80,7 +80,8 @@ The Autocomplete component supports Joy UI's four [global variants](/joy-ui/main {{"demo": "InputAppearance.js"}} :::success -To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +Note that you lose the global variants when you add custom variants. ::: ### Label diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index 07995bcd887c8a..29193c49755000 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -66,7 +66,8 @@ The Avatar component supports Joy UI's four [global variants](/joy-ui/main-featu {{"demo": "AvatarVariants.js"}} :::success -To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +Note that you lose the global variants when you add custom variants. ::: ### Sizes From 7b1b7444ed1b1a251eeea6e337945c558de2255a Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Tue, 15 Nov 2022 14:56:05 -0600 Subject: [PATCH 03/10] progress --- docs/data/joy/components/alert/alert.md | 14 +- .../components/autocomplete/autocomplete.md | 128 ++++++------------ docs/data/joy/components/avatar/avatar.md | 20 +-- 3 files changed, 57 insertions(+), 105 deletions(-) diff --git a/docs/data/joy/components/alert/alert.md b/docs/data/joy/components/alert/alert.md index a6299122f0d6f0..98c17eb2580103 100644 --- a/docs/data/joy/components/alert/alert.md +++ b/docs/data/joy/components/alert/alert.md @@ -53,13 +53,6 @@ To learn how to add your own variants, check out [Themed components—Extend var Note that you lose the global variants when you add custom variants. ::: -### Colors - -Every palette included in the theme is available via the `color` prop. -The demo below shows how the values for the `color` prop are affected by the global variants: - -{{"demo": "AlertColors.js"}} - ### Sizes The Alert component comes in three sizes: `sm`, `md` (default), and `lg`: @@ -72,6 +65,13 @@ Use the `startDecorator` and `endDecorator` props to append actions and icons to {{"demo": "AlertWithDecorators.js"}} +### Colors + +Every palette included in the theme is available via the `color` prop. +The demo below shows how the values for the `color` prop are affected by the global variants: + +{{"demo": "AlertColors.js"}} + ## Common examples ### Various states diff --git a/docs/data/joy/components/autocomplete/autocomplete.md b/docs/data/joy/components/autocomplete/autocomplete.md index 320e835e6c0973..b93886027ff96a 100644 --- a/docs/data/joy/components/autocomplete/autocomplete.md +++ b/docs/data/joy/components/autocomplete/autocomplete.md @@ -7,12 +7,11 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ # Autocomplete -

The Autocomplete component is a text input enhanced by a panel of suggested options when users start typing.

+

The autocomplete is a text input enhanced by a panel of suggested options when users start typing.

## Introduction -The Autocomplete component is an enhanced version of a text input that shows suggested options as a user types, and lets them select options from the list. -It includes many sophisticated customization options to suit a wide range of design and user experience needs. +`Autocomplete` is an enhanced version of text input that shows suggested options as the users type and also let them select an option from the list. {{"demo": "Playground.js", "hideToolbar": true}} @@ -33,30 +32,26 @@ export default function App() { ## Basics -The Autocomplete component requires a list of options, which is displayed when the input receives focus or the button is clicked. -The user must choose from this predefined set of values passed to the `options` prop. -This prop accepts either an array of strings, or an array of objects with the desired values assigned to the `label` key, as shown below: +The Autocomplete component requires a list of `options` to be displayed after the textbox is focused. The value must be chosen from a predefined set of allowed values. -```js -// options can be an array of strings... -const options = ['The Godfather', 'Pulp Fiction']; +{{"demo": "BasicAutocomplete.js"}} + +## Customization + +### Options structure -// ...or an array of objects (using the label key) +By default, the `options` accepts an array of `string` or `{ label: string }`: + +```js const options = [ { label: 'The Godfather', id: 1 }, { label: 'Pulp Fiction', id: 2 }, ]; - +// or +const options = ['The Godfather', 'Pulp Fiction']; ``` -{{"demo": "BasicAutocomplete.js"}} - -## Customization - -### Custom option labels - -Use the `getOptionLabel` prop to populate the Autocomplete component with values assigned to a different key than `label`. -For example, the code snippet below populates the Autocomplete with values from the `title` key instead: +However, you can use different structures by providing a `getOptionLabel` prop: ```js const options = [ @@ -69,24 +64,23 @@ const options = [ ### Option appearance -To customize the appearance of the options, use the `renderOption` prop along with the Autocomplete Option component as an option container. +To customize the appearance of the options, use `renderOption` prop in combination with the `AutocompleteOption` component as an option container. {{"demo": "CountrySelect.js"}} ### Variants -The Autocomplete component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft`, `outlined` (default), and `plain`. +The autocomplete component supports the four global variants: `outlined` (default), `soft`, `solid`, and `plain`. {{"demo": "InputAppearance.js"}} :::success -To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). -Note that you lose the global variants when you add custom variants. +To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). ::: ### Label -Put an Autocomplete, a Form Label, and a Form Helper Text (optional) under a Form Control component to create an accessible Autocomplete: +Put an `Autocomplete`, a `FormLabel` and a `FormHelperText` (optional) under a `FormControl` component to create an accessible autocomplete. {{"demo": "LabelAndHelperText.js"}} @@ -104,7 +98,7 @@ The component has two states that can be controlled: 2. the "input value" state with the `inputValue`/`onInputChange` props combination. This state represents the value displayed in the textbox. :::warning -⚠️ These two states are isolated, and should be controlled independently. +⚠️ These two states are isolated, they should be controlled independently. ::: {{"demo": "ControllableStates.js"}} @@ -131,7 +125,7 @@ It displays a progress state as long as the network request is pending. ### Search input -Use `freeSolo` to create a search input with suggestions, similar to Google search or [react-autowhatever](https://github.com/moroshko/react-autowhatever). +Use `freeSolo` to create a **search input** with suggestions experience, e.g. Google search or [react-autowhatever](https://github.com/moroshko/react-autowhatever). {{"demo": "FreeSolo.js"}} @@ -141,9 +135,9 @@ Use `freeSolo` to create a search input with suggestions, similar to Google sear The value created by typing into the textbox is always a string, regardless of the type of the options. ::: -### User-created option +### User's created option -If you intend to use `freeSolo` mode for a [combo box](#combo-box)-like experience (an enhanced version of a select element), try using: +If you intend to use `freeSolo` mode for a [combo box](#combo-box) like experience (an enhanced version of a select element) we recommend setting: - `selectOnFocus` to help the user clear the selected value. - `clearOnBlur` to help the user enter a new value. @@ -152,25 +146,25 @@ If you intend to use `freeSolo` mode for a [combo box](#combo-box)-like experien {{"demo": "FreeSoloCreateOption.js"}} -You could also display a dialog when the user wants to add a new value: +You could also display a dialog when the user wants to add a new value. {{"demo": "FreeSoloCreateOptionDialog.js"}} :::info -The Autocomplete Option component uses the same styles and variables as [List Item Button](/joy-ui/react-list/#actionable), so that you get the same customization experience. +The `AutocompleteOption` uses the same styles and variables as [`ListItemButton`](/joy-ui/react-list/#actionable), so that you get the same customization experience. ::: ### Validation -To display an invalid state, set the `error` prop on the Form Control. +To display invalid state, set the `error` prop on the `FormControl`. {{"demo": "AutocompleteError.js"}} ### Multiple selection -By default, Autocomplete uses the [Chip](/joy-ui/react-chip/) component to render the user's selected options. +By default, the autocomplete uses [`Chip`](/joy-ui/react-chip/) component to render the user's selected options. -When the Autocomplete is focused, the user can press the backspace to remove the latest selected option from the list. +When the autocomplete is focused, the user can press the backspace to remove the latest selected option from the list. {{"demo": "Tags.js"}} @@ -188,7 +182,7 @@ You can use the `limitTags` prop to limit the number of displayed options when n ### Sizes -The Autocomplete component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`. The size is propagated to internal components, including `Input`, `Chip`, and `List`. +The autocomplete component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`. The size is propagated to internal components, including `Input`, `Chip`, and `List`. {{"demo": "Sizes.js"}} @@ -196,7 +190,7 @@ The Autocomplete component comes with three sizes out of the box: `sm`, `md` (th To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). ::: -The `size` can also be controlled at the Form Control. +The `size` can also be controlled at the `FormControl`. {{"demo": "SizeWithLabel.js"}} @@ -239,7 +233,7 @@ const filterOptions = createFilterOptions({ ### Advanced filter -For richer filtering mechanisms, like fuzzy matching, try using [match-sorter](https://github.com/kentcdodds/match-sorter) as a reference point. For instance: +For richer filtering mechanisms, like fuzzy matching, it's recommended to look at [match-sorter](https://github.com/kentcdodds/match-sorter). For instance: ```jsx import { matchSorter } from 'match-sorter'; @@ -257,23 +251,21 @@ The following demo relies on [autosuggest-highlight](https://github.com/moroshko {{"demo": "Highlights.js"}} -### GitHub label picker +### GitHub's picker -To reproduce GitHub's label picker, the Autocomplete is rendered inside an [Unstyled Popper](/base/react-popper/). -To remove the popup behavior from the autocomplete, replace the listbox slot with the Autocomplete Listbox component. +To reproduce GitHub's label picker, the `Autocomplete` is rendered inside a [`PopperUnstyled`](/base/react-popper/). To remove the popup behavior from the autocomplete, replace the listbox slot with the `AutocompleteListbox` component. {{"demo": "GitHubLabel.js"}} ### Virtualization -Search within 10,000 randomly-generated options. -The list is virtualized thanks to [react-window](https://github.com/bvaughn/react-window). +Search within 10,000 randomly generated options. The list is virtualized thanks to [react-window](https://github.com/bvaughn/react-window). {{"demo": "Virtualize.js"}} ## Events -To prevent the default key handler behavior, you can set the event's `defaultMuiPrevented` property to `true`: +If you would like to prevent the default key handler behavior, you can set the event's `defaultMuiPrevented` property to `true`: ```jsx ` and a ` -
-``` diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index 29193c49755000..d0585541b96876 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -33,8 +33,6 @@ export default function MyApp() { By default, the Avatar component displays a generic Person Icon. Wrap it around a string to display plain text, or use the `src` prop to display an image. -## Customization - ### Text Avatar Wrap the Avatar component around a string to display text. @@ -49,7 +47,7 @@ Make sure to to write a meaningful description for the `alt` prop. {{"demo": "ImageAvatars.js"}} -### Image fallbacks +#### Image fallbacks If an error occurs while loading the Avatar's image, it will fall back to the following alternatives (in this order): @@ -59,6 +57,8 @@ If an error occurs while loading the Avatar's image, it will fall back to the fo {{"demo": "FallbackAvatars.js"}} +## Customization + ### Variants The Avatar component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. @@ -80,13 +80,7 @@ The Avatar component comes in three sizes: `sm`, `md` (default), and `lg`: To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). ::: -## Usage with the Badge - -Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually communicate more complex information about a user's status: - -{{"demo": "BadgeAvatars.js"}} - -## Usage with the Avatar Group +## Usage with Avatar Group Use the Avatar Group component to group multiple Avatars together. @@ -132,6 +126,12 @@ This approach is preferable because it preserves the overlapping offset between {{"demo": "VerticalAvatarGroup.js"}} +## Usage with Badge + +Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually communicate more complex information about a user's status: + +{{"demo": "BadgeAvatars.js"}} + ## CSS variable playground Play around with the CSS variables available to the Avatar component to see how the design changes. From 61595eb9c35b40565ac6b7f4b29cc4ac6e2bbeb3 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Tue, 15 Nov 2022 15:28:22 -0600 Subject: [PATCH 04/10] colors then decorators --- docs/data/joy/components/alert/alert.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/data/joy/components/alert/alert.md b/docs/data/joy/components/alert/alert.md index 98c17eb2580103..7b7e261e99ba94 100644 --- a/docs/data/joy/components/alert/alert.md +++ b/docs/data/joy/components/alert/alert.md @@ -59,12 +59,6 @@ The Alert component comes in three sizes: `sm`, `md` (default), and `lg`: {{"demo": "AlertSizes.js"}} -### Decorators - -Use the `startDecorator` and `endDecorator` props to append actions and icons to either side of the Alert: - -{{"demo": "AlertWithDecorators.js"}} - ### Colors Every palette included in the theme is available via the `color` prop. @@ -72,6 +66,12 @@ The demo below shows how the values for the `color` prop are affected by the glo {{"demo": "AlertColors.js"}} +### Decorators + +Use the `startDecorator` and `endDecorator` props to append actions and icons to either side of the Alert: + +{{"demo": "AlertWithDecorators.js"}} + ## Common examples ### Various states From 38e1adecd29cd284b2b8ddf2154b9201564afe4b Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Tue, 15 Nov 2022 15:47:38 -0600 Subject: [PATCH 05/10] usage not component --- docs/data/joy/components/avatar/avatar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index d0585541b96876..899a1e6e854da7 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -16,7 +16,7 @@ The Avatar component can be used to display graphical information about a user i {{"component": "modules/components/ComponentLinkHeader.js", "design": false}} -## Component +## Usage After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: From c39366967c6bb60b47fe424f954f366c9d028d07 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Wed, 16 Nov 2022 11:50:19 -0600 Subject: [PATCH 06/10] remove usage, move import to basics --- docs/data/joy/components/alert/alert.md | 10 +--------- docs/data/joy/components/aspect-ratio/aspect-ratio.md | 10 +--------- docs/data/joy/components/avatar/avatar.md | 10 +--------- 3 files changed, 3 insertions(+), 27 deletions(-) diff --git a/docs/data/joy/components/alert/alert.md b/docs/data/joy/components/alert/alert.md index 7b7e261e99ba94..0e59224b6233cf 100644 --- a/docs/data/joy/components/alert/alert.md +++ b/docs/data/joy/components/alert/alert.md @@ -22,20 +22,12 @@ Use the Joy UI [Modal](https://mui.com/joy-ui/react-modal/) if you need the beha {{"component": "modules/components/ComponentLinkHeader.js", "design": false}} -## Usage - -After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: +## Basics ```jsx import Alert from '@mui/joy/Alert'; - -export default function MyApp() { - return ; -} ``` -## Basics - The Alert component wraps around its content, and stretches to fill its enclosing container, as shown below: {{"demo": "AlertBasic.js"}} diff --git a/docs/data/joy/components/aspect-ratio/aspect-ratio.md b/docs/data/joy/components/aspect-ratio/aspect-ratio.md index d1a4dffca44f7f..88eb6d0dfa53cb 100644 --- a/docs/data/joy/components/aspect-ratio/aspect-ratio.md +++ b/docs/data/joy/components/aspect-ratio/aspect-ratio.md @@ -18,20 +18,12 @@ As of Q4 2022, compatibility is at 90%. Source: [Can I use…](https://caniuse.com/?search=aspect-ratio) ::: -## Usage - -After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: +## Basics ```jsx import AspectRatio from '@mui/joy/AspectRatio'; - -export default function MyApp() { - return ; -} ``` -## Basics - The Aspect Ratio component wraps around the content that it resizes. The element to be resized must be the first direct child. The default ratio is `16/9`. diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index 899a1e6e854da7..3f7f96377250bf 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -16,20 +16,12 @@ The Avatar component can be used to display graphical information about a user i {{"component": "modules/components/ComponentLinkHeader.js", "design": false}} -## Usage - -After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: +## Basics ```jsx import Avatar from '@mui/joy/Avatar'; - -export default function MyApp() { - return ; -} ``` -## Basics - By default, the Avatar component displays a generic Person Icon. Wrap it around a string to display plain text, or use the `src` prop to display an image. From 13dd55a60c74e6872e816a86fccabfe13cc55e66 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Wed, 16 Nov 2022 13:30:36 -0600 Subject: [PATCH 07/10] basic avatars demo --- docs/data/joy/components/avatar/BasicAvatar.js | 6 ++++++ .../joy/components/avatar/BasicAvatar.tsx.preview | 1 + docs/data/joy/components/avatar/BasicAvatars.js | 13 +++++++++++++ docs/data/joy/components/avatar/BasicAvatars.tsx | 13 +++++++++++++ .../joy/components/avatar/BasicAvatars.tsx.preview | 3 +++ docs/data/joy/components/avatar/avatar.md | 4 +++- 6 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 docs/data/joy/components/avatar/BasicAvatar.js create mode 100644 docs/data/joy/components/avatar/BasicAvatar.tsx.preview create mode 100644 docs/data/joy/components/avatar/BasicAvatars.js create mode 100644 docs/data/joy/components/avatar/BasicAvatars.tsx create mode 100644 docs/data/joy/components/avatar/BasicAvatars.tsx.preview diff --git a/docs/data/joy/components/avatar/BasicAvatar.js b/docs/data/joy/components/avatar/BasicAvatar.js new file mode 100644 index 00000000000000..e2ac407dfae025 --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatar.js @@ -0,0 +1,6 @@ +import * as React from 'react'; +import Avatar from '@mui/joy/Avatar'; + +export default function BasicAvatar() { + return ; +} diff --git a/docs/data/joy/components/avatar/BasicAvatar.tsx.preview b/docs/data/joy/components/avatar/BasicAvatar.tsx.preview new file mode 100644 index 00000000000000..23517495fdf8ab --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatar.tsx.preview @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/data/joy/components/avatar/BasicAvatars.js b/docs/data/joy/components/avatar/BasicAvatars.js new file mode 100644 index 00000000000000..92ce23634a12de --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatars.js @@ -0,0 +1,13 @@ +import * as React from 'react'; +import Avatar from '@mui/joy/Avatar'; +import Box from '@mui/joy/Box'; + +export default function BasicAvatars() { + return ( + + + JG + + + ); +} diff --git a/docs/data/joy/components/avatar/BasicAvatars.tsx b/docs/data/joy/components/avatar/BasicAvatars.tsx new file mode 100644 index 00000000000000..92ce23634a12de --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatars.tsx @@ -0,0 +1,13 @@ +import * as React from 'react'; +import Avatar from '@mui/joy/Avatar'; +import Box from '@mui/joy/Box'; + +export default function BasicAvatars() { + return ( + + + JG + + + ); +} diff --git a/docs/data/joy/components/avatar/BasicAvatars.tsx.preview b/docs/data/joy/components/avatar/BasicAvatars.tsx.preview new file mode 100644 index 00000000000000..39b1405e527ec3 --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatars.tsx.preview @@ -0,0 +1,3 @@ + +JG + \ No newline at end of file diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index 3f7f96377250bf..d0a7ea82e050ce 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -23,7 +23,9 @@ import Avatar from '@mui/joy/Avatar'; ``` By default, the Avatar component displays a generic Person Icon. -Wrap it around a string to display plain text, or use the `src` prop to display an image. +You can replace this icon with a text string or an image. + +{{"demo": "BasicAvatars.js"}} ### Text Avatar From 36b89929770aee469856b9f649946aabb8c80250 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Wed, 16 Nov 2022 13:33:00 -0600 Subject: [PATCH 08/10] consistent solid soft outlined plain --- docs/data/joy/components/avatar/AvatarVariants.js | 2 +- docs/data/joy/components/avatar/AvatarVariants.tsx | 2 +- docs/data/joy/components/avatar/AvatarVariants.tsx.preview | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/data/joy/components/avatar/AvatarVariants.js b/docs/data/joy/components/avatar/AvatarVariants.js index 1bc80bcf652dc7..6193bafcb947c9 100644 --- a/docs/data/joy/components/avatar/AvatarVariants.js +++ b/docs/data/joy/components/avatar/AvatarVariants.js @@ -5,8 +5,8 @@ import Box from '@mui/joy/Box'; export default function AvatarVariants() { return ( - + diff --git a/docs/data/joy/components/avatar/AvatarVariants.tsx b/docs/data/joy/components/avatar/AvatarVariants.tsx index 1bc80bcf652dc7..6193bafcb947c9 100644 --- a/docs/data/joy/components/avatar/AvatarVariants.tsx +++ b/docs/data/joy/components/avatar/AvatarVariants.tsx @@ -5,8 +5,8 @@ import Box from '@mui/joy/Box'; export default function AvatarVariants() { return ( - + diff --git a/docs/data/joy/components/avatar/AvatarVariants.tsx.preview b/docs/data/joy/components/avatar/AvatarVariants.tsx.preview index fa5e66d9f5ae97..0570a58cf0989f 100644 --- a/docs/data/joy/components/avatar/AvatarVariants.tsx.preview +++ b/docs/data/joy/components/avatar/AvatarVariants.tsx.preview @@ -1,4 +1,4 @@ - + \ No newline at end of file From c99d306d6fc1f3d138281ad6c456a08c404e2565 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Wed, 16 Nov 2022 13:39:59 -0600 Subject: [PATCH 09/10] imports in usage with --- docs/data/joy/components/aspect-ratio/aspect-ratio.md | 2 +- docs/data/joy/components/avatar/avatar.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/data/joy/components/aspect-ratio/aspect-ratio.md b/docs/data/joy/components/aspect-ratio/aspect-ratio.md index 88eb6d0dfa53cb..f92f7056a29639 100644 --- a/docs/data/joy/components/aspect-ratio/aspect-ratio.md +++ b/docs/data/joy/components/aspect-ratio/aspect-ratio.md @@ -81,7 +81,7 @@ When the Aspect Ratio component is a child of a flexbox `row` container, use `fl {{"demo": "FlexRowRatio.js"}} -## Usage with Next.js Image component +## Usage with Next.js Image The Aspect Ratio component can be used with a [Next.js Image](https://nextjs.org/docs/basic-features/image-optimization) component as a child. The Image should always include the `layout="fill"` property—otherwise it requires `height` and `width` values, which would defeat the purpose of the Aspect Ratio component. diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index d0a7ea82e050ce..f482e46f564ade 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -76,12 +76,12 @@ To learn how to add custom sizes to the component, check out [Themed components ## Usage with Avatar Group -Use the Avatar Group component to group multiple Avatars together. - ```jsx import AvatarGroup from '@mui/joy/AvatarGroup'; ``` +Use the Avatar Group component to group multiple Avatars together. + {{"demo": "GroupedAvatars.js"}} ### Quantity within a group @@ -122,6 +122,10 @@ This approach is preferable because it preserves the overlapping offset between ## Usage with Badge +```jsx +import Badge from '@mui/joy/Badge'; +``` + Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually communicate more complex information about a user's status: {{"demo": "BadgeAvatars.js"}} From f39869f1277dbaa7f4113a3c4c2a5a2c12163442 Mon Sep 17 00:00:00 2001 From: Olivier Tassinari Date: Thu, 17 Nov 2022 00:07:13 +0100 Subject: [PATCH 10/10] simplify Colors demo --- docs/data/joy/components/alert/AlertColors.js | 25 ++++++------------- .../data/joy/components/alert/AlertColors.tsx | 25 ++++++------------- 2 files changed, 14 insertions(+), 36 deletions(-) diff --git a/docs/data/joy/components/alert/AlertColors.js b/docs/data/joy/components/alert/AlertColors.js index 3b0fe7392edf47..1425c169eab282 100644 --- a/docs/data/joy/components/alert/AlertColors.js +++ b/docs/data/joy/components/alert/AlertColors.js @@ -1,11 +1,12 @@ +import * as React from 'react'; import Alert from '@mui/joy/Alert'; +import Stack from '@mui/joy/Stack'; import Box from '@mui/joy/Box'; import Radio from '@mui/joy/Radio'; import RadioGroup from '@mui/joy/RadioGroup'; import Sheet from '@mui/joy/Sheet'; import Typography from '@mui/joy/Typography'; -import * as React from 'react'; export default function AlertColors() { const [variant, setVariant] = React.useState('solid'); @@ -14,16 +15,11 @@ export default function AlertColors() { sx={{ display: 'flex', alignItems: 'center', - gap: 3, + justifyContent: 'center', + width: '100%', }} > - + Primary @@ -42,15 +38,8 @@ export default function AlertColors() { Warning - - + + ('solid'); @@ -14,16 +15,11 @@ export default function AlertColors() { sx={{ display: 'flex', alignItems: 'center', - gap: 3, + justifyContent: 'center', + width: '100%', }} > - + Primary @@ -42,15 +38,8 @@ export default function AlertColors() { Warning - - + +