diff --git a/docs/API.md b/docs/API.md index 8ea522b2..d798ed5c 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,5 +1,5 @@ # API Reference -The components and higher-order components (HOCs) described below are publicly exposed in the top-level module. Other components should be considered private and subject to change without notice. +The components and hooks described below are publicly exposed in the top-level module. Other components should be considered private and subject to change without notice. #### [Components](#components-1) - [``](#typeahead) @@ -13,10 +13,10 @@ The components and higher-order components (HOCs) described below are publicly e - [``](#typeaheadmenu) - [``](#token) -#### [Higher-Order Components & Hooks](#higher-order-components--hooks-1) -- [`useAsync` & `withAsync`](#useasync--withasync) -- [`useItem` & `withItem`](#useitem--withitem) -- [`useToken` & `withToken`](#usetoken--withtoken) +#### [Hooks](#hooks-1) +- [`useAsync`](#useasync) +- [`useItem`](#useitem) +- [`useToken`](#usetoken) - [`useHint`](#useHint) ## Components @@ -108,9 +108,11 @@ An enhanced version of the normal `Typeahead` component for use when performing Note that this component is the same as: ```jsx -import { Typeahead, withAsync } from 'react-bootstrap-typeahead'; +import { Typeahead, useAsync } from 'react-bootstrap-typeahead'; -const AsyncTypeahead = withAsync(Typeahead); +const AsyncTypeahead = forwardRef((props, ref) => { + return ; +}); ``` #### Props @@ -186,7 +188,7 @@ id `required` | string \| number | | Id value required for accessibility. maxHeight | string | `'300px'` | Maximum height of the dropdown menu. ### `` -Provides the markup for a Bootstrap menu item, but is wrapped by the [`withItem` HOC](#useitem--withitem) to ensure proper behavior within the typeahead context. Provided for use if a more customized `Menu` is desired. +Provides the markup for a Bootstrap menu item, but uses the [`useItem` hook](#useitem) to ensure proper behavior within the typeahead context. Provided for use if a more customized `Menu` is desired. #### Props Name | Type | Default | Description @@ -228,21 +230,17 @@ tabIndex | number | `0` | Allows the tabindex to be set if something other than ## Higher-Order Components & Hooks -### `useAsync` & `withAsync` -The HOC used in [`AsyncTypeahead`](#asynctypeahead). +### `useAsync` +The hook used in [`AsyncTypeahead`](#asynctypeahead). -### `useItem` & `withItem` +### `useItem` Connects individual menu items with the main typeahead component via context and abstracts a lot of complex functionality required for behaviors like keying through the menu and input hinting. Also provides `onClick` behavior and active state. -If you use your own menu item components (in `renderMenu` for example), you are strongly advised to use either the hook or the HOC: +If you use your own menu item components (in `renderMenu` for example), you are strongly advised to use the hook to retain correct behaviors: ```jsx import { MenuItem } from 'react-bootstrap'; -import { Menu, Typeahead, useItem, withItem } from 'react-bootstrap-typeahead'; - -const Item = withItem(MenuItem); - -// OR +import { Menu, Typeahead, useItem } from 'react-bootstrap-typeahead'; const Item = (props) => ; @@ -259,8 +257,8 @@ const Item = (props) => ; /> ``` -### `useToken` & `withToken` -Encapsulates keystroke and outside click behaviors used in `Token`. Useful if you want completely custom markup for the token. The hook and the HOC provide the following props to be consumed by the token component: +### `useToken` +Encapsulates keystroke and outside click behaviors used in `Token`. Useful if you want completely custom markup for the token. Provides the following props to be consumed by the token component: Name | Type | Description -----|------|------------ @@ -285,10 +283,6 @@ const MyToken = forwardRef(({ active, onRemove, ...props }, ref) => ( )); -// HOC -const CustomToken = withToken(MyToken); - -// Hook const CustomToken = (props) => ; ``` If using the hook, you can also apply it directly within your token component: diff --git a/docs/Upgrading.md b/docs/Upgrading.md index f47f49ff..45109834 100644 --- a/docs/Upgrading.md +++ b/docs/Upgrading.md @@ -1,5 +1,6 @@ # Upgrade Guide +- [Version 7.0](Upgrading.md#v70-breaking-changes) - [Version 6.0](Upgrading.md#v60-breaking-changes) - [Version 5.0](Upgrading.md#v50-breaking-changes) - [Version 4.0](Upgrading.md#v40-breaking-changes) @@ -7,6 +8,15 @@ - [Version 2.0](Upgrading.md#v20) - [Version 1.0](Upgrading.md#v10) +## v7.0 Breaking Changes + +### HOCs removed in favor of hooks +The following HOCs were deprecated in a previous version and have been removed: + +- `withAsync` (use `useAsync`) +- `withItem` (use `useItem`) +- `withToken` (use `useToken`) + ## v6.0 Breaking Changes ### `"small"` and `"large"` are no longer valid `size` values