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}
+
+ );
+};
+
+
+```
+
+
+ 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';