diff --git a/packages/@react-aria/autocomplete/docs/useAutocomplete.mdx b/packages/@react-aria/autocomplete/docs/useAutocomplete.mdx index 35c4f8f9d60..58f4168daa8 100644 --- a/packages/@react-aria/autocomplete/docs/useAutocomplete.mdx +++ b/packages/@react-aria/autocomplete/docs/useAutocomplete.mdx @@ -12,9 +12,10 @@ export default Layout; import docs from 'docs:@react-aria/autocomplete'; import {FunctionAPI, HeaderInfo, InterfaceType, TypeContext, TypeLink, PageDescription} from '@react-spectrum/docs'; +import i18nDocs from 'docs:@react-aria/i18n'; import packageData from '@react-aria/autocomplete/package.json'; import statelyDocs from 'docs:@react-stately/autocomplete'; -import {InlineAlert, Content, Heading} from '@adobe/react-spectrum'; +import ChevronRight from '@spectrum-icons/workflow/ChevronRight'; --- category: Pickers @@ -31,11 +32,6 @@ preRelease: beta componentNames={['useAutocomplete']} /> - - Under construction - This hook is in beta. More documentation is coming soon! - - ## API @@ -45,6 +41,13 @@ preRelease: beta Autocomplete can be implemented using the [<datalist>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist) HTML element, but this has limited functionality and behaves differently across browsers. `useAutocomplete` helps achieve accessible text input and collection that can be styled as needed. +`useAutocomplete` can be used to build UI patterns such as command palettes, searchable menus, and filterable selects. + +* **Flexible** – Support for multiple input types and collection types, controlled and uncontrolled state, and custom filter functions. +* **Keyboard navigation** – an Autocomplete can be navigated using the arrow keys, along with page up/down, home/end, etc. The list of options is filtered while typing into the input, and items can be selected with the enter key. +* **Accessible** – Follows the [ARIA autocomplete pattern](https://w3c.github.io/aria/#aria-autocomplete), with support for any [collections](../react-aria/collections.html). + + ## Anatomy An autocomplete consists of a text input that displays the current value and a collection of items. Users can type within the input @@ -59,6 +62,129 @@ to filter the collection. `useAutocomplete` handles exposing the correct ARIA at State is managed by the hook from `@react-stately/autocomplete`. The state object should be passed as an option to `useAutocomplete`. + +## Example + +This example uses [React Aria Components](../react-aria/components.html) and shows how, if you need to build your own `Autocomplete` component, you can integrate it with existing React Aria Components. +This `Autocomplete` uses a [SearchField](./SearchField.html) as the input and controls a [ListBox](./ListBox.html). +See those docs for examples of what they can do or how to customize them. This `Autocomplete` renders no dom, so see those components for styling as well. + +```tsx example +import {AriaAutocompleteProps, useAutocomplete} from '@react-aria/autocomplete'; +import {useAutocompleteState} from '@react-stately/autocomplete'; +import {useRef} from 'react'; +import { + Label, + Text, + InputContext, + Input, + Provider, + SearchFieldContext, + SearchField, + ListBox, + ListBoxItem, + useFilter, + UNSTABLE_InternalAutocompleteContext +} from 'react-aria-components' + +interface AutocompleteProps extends AriaAutocompleteProps {} + +function Autocomplete(props: AutocompleteProps) { + let {contains} = useFilter({ sensitivity: 'base' }); + let state = useAutocompleteState(props); + let inputRef = useRef(null); + let collectionRef = useRef(null); + let { + textFieldProps, + collectionProps, + collectionRef: mergedCollectionRef, + filter: filterFn + } = useAutocomplete({ + ...props, + filter: contains, + inputRef, + collectionRef + }, state); + + return ( + + {props.children} + + ); +}; + +
+ + + + + Please select a pet below. + + + Red Panda + Cat + Dog + Aardvark + Kangaroo + Snake + + +
+``` + +
+ Show CSS +```css hidden +@import '../../../react-aria-components/docs/Checkbox.mdx' layer(checkbox); +@import '../../../react-aria-components/docs/SearchField.mdx' layer(searchfield); +@import '../../../react-aria-components/docs/ListBox.mdx' layer(listbox); +``` + +```css +@import "@react-aria/example-theme"; + +.autocomplete { + display: flex; + flex-direction: column; + gap: 12px; + max-width: 300px; + height: 180px; + border: 1px solid var(--border-color); + padding: 16px; + border-radius: 10px; + background: var(--overlay-background); + + .react-aria-SearchField { + width: 100%; + } + + .react-aria-ListBox { + flex: 1; + overflow: auto; + } + + .react-aria-Label { + margin-bottom: .5em; + } +} +``` + +
+ +## Styled examples + +See [Autocomplete examples](https://react-spectrum.adobe.com/react-aria/Autocomplete.html#examples) for a sense of the things that you can build with the `useAutocomplete` hook. + + ## Internationalization `useAutocomplete` handles some aspects of internationalization automatically. diff --git a/packages/@react-stately/autocomplete/docs/useAutocompleteState.mdx b/packages/@react-stately/autocomplete/docs/useAutocompleteState.mdx index 10962de8d01..2f4ce7adb3d 100644 --- a/packages/@react-stately/autocomplete/docs/useAutocompleteState.mdx +++ b/packages/@react-stately/autocomplete/docs/useAutocompleteState.mdx @@ -42,3 +42,7 @@ preRelease: beta +## Example + +See the docs for [useAutocomplete](/react-aria/useAutocomplete.html) in react-aria for an example of `useAutocompleteState`. + diff --git a/packages/react-aria-components/src/index.ts b/packages/react-aria-components/src/index.ts index 4dd0ad67ed4..9b2fcb58d83 100644 --- a/packages/react-aria-components/src/index.ts +++ b/packages/react-aria-components/src/index.ts @@ -16,7 +16,7 @@ import 'client-only'; export {CheckboxContext, ColorAreaContext, ColorFieldContext, ColorSliderContext, ColorWheelContext, HeadingContext} from './RSPContexts'; -export {Autocomplete, AutocompleteContext, AutocompleteStateContext} from './Autocomplete'; +export {Autocomplete, AutocompleteContext, AutocompleteStateContext, UNSTABLE_InternalAutocompleteContext} from './Autocomplete'; export {Breadcrumbs, BreadcrumbsContext, Breadcrumb} from './Breadcrumbs'; export {Button, ButtonContext} from './Button'; export {Calendar, CalendarGrid, CalendarGridHeader, CalendarGridBody, CalendarHeaderCell, CalendarCell, RangeCalendar, CalendarContext, RangeCalendarContext, CalendarStateContext, RangeCalendarStateContext} from './Calendar';