From 3c3f226cb7f0aa3b1d807b88bc01a513c8f1b11f Mon Sep 17 00:00:00 2001 From: Flavien DELANGLE Date: Tue, 21 May 2024 15:08:44 +0200 Subject: [PATCH] [docs] Unify Tree View `apiRef` methods doc examples (#13193) Signed-off-by: Flavien DELANGLE Co-authored-by: Michel Engelen <32863416+michelengelen@users.noreply.github.com> --- ...ansion.js => ApiMethodSetItemExpansion.js} | 2 +- ...sion.tsx => ApiMethodSetItemExpansion.tsx} | 2 +- ... => ApiMethodSetItemExpansion.tsx.preview} | 0 .../rich-tree-view/expansion/expansion.md | 32 +++++++++- ...dRichTreeView.js => ApiMethodFocusItem.js} | 2 +- ...ichTreeView.tsx => ApiMethodFocusItem.tsx} | 2 +- ...preview => ApiMethodFocusItem.tsx.preview} | 0 .../tree-view/rich-tree-view/focus/focus.md | 23 +++++-- .../rich-tree-view/headless/headless.md | 6 +- .../rich-tree-view/items/ApiMethodGetItem.js | 56 +++++++++++++++++ .../rich-tree-view/items/ApiMethodGetItem.tsx | 61 +++++++++++++++++++ .../items/ApiMethodGetItem.tsx.preview | 11 ++++ .../tree-view/rich-tree-view/items/items.md | 19 +++++- ...ansion.js => ApiMethodSetItemExpansion.js} | 2 +- ...sion.tsx => ApiMethodSetItemExpansion.tsx} | 2 +- .../simple-tree-view/expansion/expansion.md | 32 +++++++++- ...impleTreeView.js => ApiMethodFocusItem.js} | 2 +- ...pleTreeView.tsx => ApiMethodFocusItem.tsx} | 2 +- .../tree-view/simple-tree-view/focus/focus.md | 23 +++++-- .../useTreeViewItems.types.ts | 1 + 20 files changed, 249 insertions(+), 31 deletions(-) rename docs/data/tree-view/rich-tree-view/expansion/{ChangeItemExpansion.js => ApiMethodSetItemExpansion.js} (96%) rename docs/data/tree-view/rich-tree-view/expansion/{ChangeItemExpansion.tsx => ApiMethodSetItemExpansion.tsx} (96%) rename docs/data/tree-view/rich-tree-view/expansion/{ChangeItemExpansion.tsx.preview => ApiMethodSetItemExpansion.tsx.preview} (100%) rename docs/data/tree-view/rich-tree-view/focus/{FocusedRichTreeView.js => ApiMethodFocusItem.js} (96%) rename docs/data/tree-view/rich-tree-view/focus/{FocusedRichTreeView.tsx => ApiMethodFocusItem.tsx} (96%) rename docs/data/tree-view/rich-tree-view/focus/{FocusedRichTreeView.tsx.preview => ApiMethodFocusItem.tsx.preview} (100%) create mode 100644 docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.js create mode 100644 docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx create mode 100644 docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview rename docs/data/tree-view/simple-tree-view/expansion/{ChangeItemExpansion.js => ApiMethodSetItemExpansion.js} (96%) rename docs/data/tree-view/simple-tree-view/expansion/{ChangeItemExpansion.tsx => ApiMethodSetItemExpansion.tsx} (96%) rename docs/data/tree-view/simple-tree-view/focus/{FocusedSimpleTreeView.js => ApiMethodFocusItem.js} (96%) rename docs/data/tree-view/simple-tree-view/focus/{FocusedSimpleTreeView.tsx => ApiMethodFocusItem.tsx} (97%) diff --git a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.js b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.js similarity index 96% rename from docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.js rename to docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.js index 044944e3dadcb..54ef0fe7b1732 100644 --- a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.js +++ b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.js @@ -26,7 +26,7 @@ const MUI_X_PRODUCTS = [ }, ]; -export default function ChangeItemExpansion() { +export default function ApiMethodSetItemExpansion() { const apiRef = useTreeViewApiRef(); const handleExpandClick = (event) => { diff --git a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx similarity index 96% rename from docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx rename to docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx index 91587ed8df718..051424e259509 100644 --- a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx +++ b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx @@ -26,7 +26,7 @@ const MUI_X_PRODUCTS: TreeViewBaseItem[] = [ }, ]; -export default function ChangeItemExpansion() { +export default function ApiMethodSetItemExpansion() { const apiRef = useTreeViewApiRef(); const handleExpandClick = (event: React.MouseEvent) => { diff --git a/docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx.preview b/docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx.preview similarity index 100% rename from docs/data/tree-view/rich-tree-view/expansion/ChangeItemExpansion.tsx.preview rename to docs/data/tree-view/rich-tree-view/expansion/ApiMethodSetItemExpansion.tsx.preview diff --git a/docs/data/tree-view/rich-tree-view/expansion/expansion.md b/docs/data/tree-view/rich-tree-view/expansion/expansion.md index a44e1e07bdfb8..e36fe65d20c1e 100644 --- a/docs/data/tree-view/rich-tree-view/expansion/expansion.md +++ b/docs/data/tree-view/rich-tree-view/expansion/expansion.md @@ -33,8 +33,34 @@ Use the `onItemExpansionToggle` prop if you want to react to an item expansion c {{"demo": "TrackItemExpansionToggle.js"}} -## Change item expansion +## Imperative API -You can use the `setItemExpansion` API method to imperatively change the expansion of an item: +:::success +To use the `apiRef` object, you need to initialize it using the `useTreeViewApiRef` hook as follows: -{{"demo": "ChangeItemExpansion.js"}} +```tsx +const apiRef = useTreeViewApiRef(); + +return ; +``` + +When your component first renders, `apiRef` will be `undefined`. +After this initial render, `apiRef` holds methods to interact imperatively with the Tree View. +::: + +### Change an item expansion + +Use the `setItemExpansion` API method to change the expansion of an item. + +```ts +apiRef.current.setItemExpansion( + // The DOM event that triggered the change + event, + // The ID of the item to expand or collapse + itemId, + // `true` if the item should be expanded, `false` if it should be collapsed + isExpanded, +); +``` + +{{"demo": "ApiMethodSetItemExpansion.js"}} diff --git a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.js b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.js similarity index 96% rename from docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.js rename to docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.js index c2a96bffdf47e..4dc583c1c6a8f 100644 --- a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.js +++ b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.js @@ -35,7 +35,7 @@ const MUI_X_PRODUCTS = [ }, ]; -export default function FocusedRichTreeView() { +export default function ApiMethodFocusItem() { const apiRef = useTreeViewApiRef(); const handleButtonClick = (event) => { apiRef.current?.focusItem(event, 'pickers'); diff --git a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx similarity index 96% rename from docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx rename to docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx index 04b1aad4d11cf..364a83f58a5c3 100644 --- a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx +++ b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx @@ -35,7 +35,7 @@ const MUI_X_PRODUCTS: TreeViewBaseItem[] = [ }, ]; -export default function FocusedRichTreeView() { +export default function ApiMethodFocusItem() { const apiRef = useTreeViewApiRef(); const handleButtonClick = (event: React.SyntheticEvent) => { apiRef.current?.focusItem(event, 'pickers'); diff --git a/docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx.preview b/docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx.preview similarity index 100% rename from docs/data/tree-view/rich-tree-view/focus/FocusedRichTreeView.tsx.preview rename to docs/data/tree-view/rich-tree-view/focus/ApiMethodFocusItem.tsx.preview diff --git a/docs/data/tree-view/rich-tree-view/focus/focus.md b/docs/data/tree-view/rich-tree-view/focus/focus.md index 4fa127cea557e..7451953dac480 100644 --- a/docs/data/tree-view/rich-tree-view/focus/focus.md +++ b/docs/data/tree-view/rich-tree-view/focus/focus.md @@ -11,10 +11,7 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/

Learn how to focus Tree View items.

-## Focus a specific item - -You can use the the `apiRef.focusItem` method to focus a specific item. -This methods receives two parameters: `event` and `itemId`. +## Imperative API :::success To use the `apiRef` object, you need to initialize it using the `useTreeViewApiRef` hook as follows: @@ -25,12 +22,26 @@ const apiRef = useTreeViewApiRef(); return ; ``` -`apiRef` will be undefined during the first render and will then contain methods allowing you to imperatively interact with the Tree View. +When your component first renders, `apiRef` will be `undefined`. +After this initial render, `apiRef` holds methods to interact imperatively with the Tree View. ::: +### Focus a specific item + +Use the `focusItem` API method to focus a specific item. + +```ts +apiRef.current.focusItem( + // The DOM event that triggered the change + event, + // The ID of the item to focus + itemId, +); +``` + :::info This method only works with items that are currently visible. Calling `apiRef.focusItem` on an item whose parent is collapsed will do nothing. ::: -{{"demo": "FocusedRichTreeView.js"}} +{{"demo": "ApiMethodFocusItem.js"}} diff --git a/docs/data/tree-view/rich-tree-view/headless/headless.md b/docs/data/tree-view/rich-tree-view/headless/headless.md index a258a6e6b524f..99955f9962855 100644 --- a/docs/data/tree-view/rich-tree-view/headless/headless.md +++ b/docs/data/tree-view/rich-tree-view/headless/headless.md @@ -43,7 +43,7 @@ A custom plugins contains 2 required elements: ### Params default value -You can use the `getDefaultizedParams` property to set a default value to your plugin params: +Use the `getDefaultizedParams` property to set a default value to your plugin params: ```ts const useCustomPlugin = ({ params }) => { @@ -203,7 +203,7 @@ If you are using TypeScript, you need to define your dependencies in your plugin ### Pass props to your root element -You can use the `getRootProps` property of your returned value to pass props to your root element: +Use the `getRootProps` property of your returned value to pass props to your root element: ```ts const useCustomPlugin = ({ params }) => { @@ -217,7 +217,7 @@ const useCustomPlugin = ({ params }) => { ### Pass elements to the Tree Item -You can use the `contextValue` property in the returned object to pass elements to the Tree Item: +Use the `contextValue` property in the returned object to pass elements to the Tree Item: :::warning The context is private for now and cannot be accessed outside the provided plugins. diff --git a/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.js b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.js new file mode 100644 index 0000000000000..84b3d54baaccc --- /dev/null +++ b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.js @@ -0,0 +1,56 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import Stack from '@mui/material/Stack'; +import Typography from '@mui/material/Typography'; +import { RichTreeView } from '@mui/x-tree-view/RichTreeView'; + +import { useTreeViewApiRef } from '@mui/x-tree-view/hooks'; + +const MUI_X_PRODUCTS = [ + { + id: 'grid', + label: 'Data Grid', + children: [ + { id: 'grid-community', label: '@mui/x-data-grid' }, + { id: 'grid-pro', label: '@mui/x-data-grid-pro' }, + { id: 'grid-premium', label: '@mui/x-data-grid-premium' }, + ], + }, + { + id: 'pickers', + label: 'Date and Time Pickers', + children: [ + { id: 'pickers-community', label: '@mui/x-date-pickers' }, + { id: 'pickers-pro', label: '@mui/x-date-pickers-pro' }, + ], + }, +]; + +export default function ApiMethodGetItem() { + const apiRef = useTreeViewApiRef(); + const [selectedItem, setSelectedItem] = React.useState(null); + + const handleSelectedItemsChange = (event, itemId) => { + if (itemId == null) { + setSelectedItem(null); + } else { + setSelectedItem(apiRef.current.getItem(itemId)); + } + }; + + return ( + + + Selected item: {selectedItem == null ? 'none' : selectedItem.label} + + + + + + ); +} diff --git a/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx new file mode 100644 index 0000000000000..b21fbbc7f888b --- /dev/null +++ b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx @@ -0,0 +1,61 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import Stack from '@mui/material/Stack'; +import Typography from '@mui/material/Typography'; +import { RichTreeView } from '@mui/x-tree-view/RichTreeView'; +import { TreeViewBaseItem } from '@mui/x-tree-view/models'; +import { useTreeViewApiRef } from '@mui/x-tree-view/hooks'; + +const MUI_X_PRODUCTS: TreeViewBaseItem[] = [ + { + id: 'grid', + label: 'Data Grid', + children: [ + { id: 'grid-community', label: '@mui/x-data-grid' }, + { id: 'grid-pro', label: '@mui/x-data-grid-pro' }, + { id: 'grid-premium', label: '@mui/x-data-grid-premium' }, + ], + }, + { + id: 'pickers', + label: 'Date and Time Pickers', + children: [ + { id: 'pickers-community', label: '@mui/x-date-pickers' }, + { id: 'pickers-pro', label: '@mui/x-date-pickers-pro' }, + ], + }, +]; + +export default function ApiMethodGetItem() { + const apiRef = useTreeViewApiRef(); + const [selectedItem, setSelectedItem] = React.useState( + null, + ); + + const handleSelectedItemsChange = ( + event: React.SyntheticEvent, + itemId: string | null, + ) => { + if (itemId == null) { + setSelectedItem(null); + } else { + setSelectedItem(apiRef.current!.getItem(itemId)); + } + }; + + return ( + + + Selected item: {selectedItem == null ? 'none' : selectedItem.label} + + + + + + ); +} diff --git a/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview new file mode 100644 index 0000000000000..640e65a388c39 --- /dev/null +++ b/docs/data/tree-view/rich-tree-view/items/ApiMethodGetItem.tsx.preview @@ -0,0 +1,11 @@ + + Selected item: {selectedItem == null ? 'none' : selectedItem.label} + + + + \ No newline at end of file diff --git a/docs/data/tree-view/rich-tree-view/items/items.md b/docs/data/tree-view/rich-tree-view/items/items.md index e85d35328c698..053934eabefae 100644 --- a/docs/data/tree-view/rich-tree-view/items/items.md +++ b/docs/data/tree-view/rich-tree-view/items/items.md @@ -119,9 +119,9 @@ Otherwise, the Tree View will re-generate its entire structure. This can be achieved by either defining the prop outside the component scope or by memoizing using the `React.useCallback` hook if the function reuses something from the component scope. ::: -### The disabledItemsFocusable prop +### Focus disabled items -Use the `disabledItemsFocusable` prop to control whether or not a disabled Tree Item can be focused. +Use the `disabledItemsFocusable` prop to control if disabled Tree Items can be focused. When this prop is set to false: @@ -140,3 +140,18 @@ When it's set to true: - Mouse or keyboard interaction will not select disabled items. - Shift + arrow keys will not skip disabled items, but the disabled item will not be selected. - Programmatic focus will focus disabled items. + +## Imperative API + +### Get an item by ID + +Use the `getItem` API method to get an item by its ID. + +```ts +const item = apiRef.current.getItem( + // The ID of the item to retrieve + itemId, +); +``` + +{{"demo": "ApiMethodGetItem.js", "defaultCodeOpen": false}} diff --git a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.js b/docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.js similarity index 96% rename from docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.js rename to docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.js index 7af3290f9f7ed..4015d5b926f4a 100644 --- a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.js +++ b/docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.js @@ -6,7 +6,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; import { TreeItem } from '@mui/x-tree-view/TreeItem'; import { useTreeViewApiRef } from '@mui/x-tree-view/hooks'; -export default function ChangeItemExpansion() { +export default function ApiMethodSetItemExpansion() { const apiRef = useTreeViewApiRef(); const handleExpandClick = (event) => { diff --git a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.tsx b/docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.tsx similarity index 96% rename from docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.tsx rename to docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.tsx index ceddc17a3a266..ea0bfb3d3cab5 100644 --- a/docs/data/tree-view/simple-tree-view/expansion/ChangeItemExpansion.tsx +++ b/docs/data/tree-view/simple-tree-view/expansion/ApiMethodSetItemExpansion.tsx @@ -6,7 +6,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; import { TreeItem } from '@mui/x-tree-view/TreeItem'; import { useTreeViewApiRef } from '@mui/x-tree-view/hooks'; -export default function ChangeItemExpansion() { +export default function ApiMethodSetItemExpansion() { const apiRef = useTreeViewApiRef(); const handleExpandClick = (event: React.MouseEvent) => { diff --git a/docs/data/tree-view/simple-tree-view/expansion/expansion.md b/docs/data/tree-view/simple-tree-view/expansion/expansion.md index d984b1bfb8137..a6b0a3f4e46ac 100644 --- a/docs/data/tree-view/simple-tree-view/expansion/expansion.md +++ b/docs/data/tree-view/simple-tree-view/expansion/expansion.md @@ -32,8 +32,34 @@ Use the `onItemExpansionToggle` prop to trigger an action upon an item being exp {{"demo": "TrackItemExpansionToggle.js"}} -## Change item expansion +## Imperative API -You can use the `setItemExpansion` API method to imperatively change the expansion of an item: +:::success +To use the `apiRef` object, you need to initialize it using the `useTreeViewApiRef` hook as follows: -{{"demo": "ChangeItemExpansion.js"}} +```tsx +const apiRef = useTreeViewApiRef(); + +return {children}; +``` + +When your component first renders, `apiRef` will be `undefined`. +After this initial render, `apiRef` holds methods to interact imperatively with the Tree View. +::: + +### Change an item expansion + +Use the `setItemExpansion` API method to change the expansion of an item. + +```ts +apiRef.current.setItemExpansion( + // The DOM event that triggered the change + event, + // The ID of the item to expand or collapse + itemId, + // `true` if the item should be expanded, `false` if it should be collapsed + isExpanded, +); +``` + +{{"demo": "ApiMethodSetItemExpansion.js"}} diff --git a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js b/docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.js similarity index 96% rename from docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js rename to docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.js index 9e12cc3ce0609..97950e48843af 100644 --- a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.js +++ b/docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.js @@ -5,7 +5,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; import { TreeItem } from '@mui/x-tree-view/TreeItem'; import { useTreeViewApiRef } from '@mui/x-tree-view/hooks/useTreeViewApiRef'; -export default function FocusedSimpleTreeView() { +export default function ApiMethodFocusItem() { const apiRef = useTreeViewApiRef(); const handleButtonClick = (event) => { apiRef.current?.focusItem(event, 'pickers'); diff --git a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx b/docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.tsx similarity index 97% rename from docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx rename to docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.tsx index bc98ac6e25a9b..919cd401fb6f4 100644 --- a/docs/data/tree-view/simple-tree-view/focus/FocusedSimpleTreeView.tsx +++ b/docs/data/tree-view/simple-tree-view/focus/ApiMethodFocusItem.tsx @@ -5,7 +5,7 @@ import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; import { TreeItem } from '@mui/x-tree-view/TreeItem'; import { useTreeViewApiRef } from '@mui/x-tree-view/hooks/useTreeViewApiRef'; -export default function FocusedSimpleTreeView() { +export default function ApiMethodFocusItem() { const apiRef = useTreeViewApiRef(); const handleButtonClick = (event: React.SyntheticEvent) => { apiRef.current?.focusItem(event, 'pickers'); diff --git a/docs/data/tree-view/simple-tree-view/focus/focus.md b/docs/data/tree-view/simple-tree-view/focus/focus.md index b408b02c9f35d..d1596614823c5 100644 --- a/docs/data/tree-view/simple-tree-view/focus/focus.md +++ b/docs/data/tree-view/simple-tree-view/focus/focus.md @@ -11,10 +11,7 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/

Learn how to focus Tree View items.

-## Focus a specific item - -You can use the the `apiRef.focusItem` method to focus a specific item. -This methods receives two parameters: `event` and `itemId`. +## Imperative API :::success To use the `apiRef` object, you need to initialize it using the `useTreeViewApiRef` hook as follows: @@ -25,12 +22,26 @@ const apiRef = useTreeViewApiRef(); return {children}; ``` -`apiRef` will be undefined during the first render and will then contain methods allowing you to imperatively interact with the Tree View. +When your component first renders, `apiRef` will be `undefined`. +After this initial render, `apiRef` holds methods to interact imperatively with the Tree View. ::: +### Focus a specific item + +Use the `focusItem` API method to focus a specific item. + +```ts +apiRef.current.focusItem( + // The DOM event that triggered the change + event, + // The ID of the item to focus + itemId, +); +``` + :::info This method only works with items that are currently visible. Calling `apiRef.focusItem` on an item whose parent is collapsed will do nothing. ::: -{{"demo": "FocusedSimpleTreeView.js"}} +{{"demo": "ApiMethodFocusItem.js"}} diff --git a/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts b/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts index 3862f2d5d51df..327907342d612 100644 --- a/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts +++ b/packages/x-tree-view/src/internals/plugins/useTreeViewItems/useTreeViewItems.types.ts @@ -11,6 +11,7 @@ interface TreeViewItemProps { export interface UseTreeViewItemsPublicAPI { /** * Get the item with the given id. + * When used in the `SimpleTreeView`, it returns an object with the `id` and `label` properties. * @param {string} itemId The id of the item to return. * @returns {R} The item with the given id. */