Skip to content

Commit

Permalink
docs: adds info on useSelection and useStepNav hooks (#10683)
Browse files Browse the repository at this point in the history
### What?
This PR adds information and examples on the `useSelection` and
`useStepNav` hooks.

### Why?
To provide more information on the React hooks available to end-users.

### How?
Changes to `admin/hooks.mdx`
  • Loading branch information
akhrarovsaid authored Jan 22, 2025
1 parent 6d43910 commit d8682f2
Showing 1 changed file with 68 additions and 0 deletions.
68 changes: 68 additions & 0 deletions docs/admin/hooks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -764,6 +764,45 @@ The `useListQuery` hook returns an object with the following properties:
| **`handleWhereChange`** | A method to handle where changes in the List View. |
| **`query`** | The current query that is being used to fetch the data in the List View. |

## useSelection

The `useSelection` hook provides information on the selected rows in the List view as well as helper methods to simplify selection. The `useSelection` hook returns an object with the following properties:

| Property | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`count`** | The number of currently selected rows. |
| **`getQueryParams`** | A function that generates a query string based on the current selection state and optional additional filtering parameters. |
| **`selectAll`** | An enum value representing the selection range: `'allAvailable'`, `'allInPage'`, `'none'`, and `'some'`. The enum, `SelectAllStatus`, is exported for easier comparisons. |
| **`selected`** | A map of document id keys and boolean values representing their selection status. |
| **`setSelection`** | A function that toggles the selection status of a document row. |
| **`toggleAll`** | A function that toggles selection for all documents on the current page or selects all available documents when passed `true`. |
| **`totalDocs`** | The number of total documents in the collection. |

**Example:**

```tsx
'use client'
import { useSelection } from '@payloadcms/ui'

const MyComponent: React.FC = () => {
// highlight-start
const { count, toggleAll, totalDocs } = useSelection()
// highlight-end

return (
<>
<span>Selected {count} out of {totalDocs} docs!</span>
<button
type="button"
onClick={() => toggleAll(true)}
>
Toggle All Selections
</button>
</>
)
}
```

## useLocale

In any Custom Component you can get the selected locale object with the `useLocale` hook. `useLocale` gives you the full locale object, consisting of a `label`, `rtl`(right-to-left) property, and then `code`. Here is a simple example:
Expand Down Expand Up @@ -948,3 +987,32 @@ const ListenForUpdates: React.FC = () => {
Right now the `useDocumentEvents` hook only tracks recently updated documents, but in the future
it will track more document-related events as needed, such as document creation, deletion, etc.
</Banner>

## useStepNav

The `useStepNav` hook provides a way to change the step-nav breadcrumb links in the app header.

| Property | Description |
| ---------------- | --------------------------------------------------------------------------------- |
| **`setStepNav`** | A state setter function which sets the `stepNav` array. |
| **`stepNav`** | A `StepNavItem` array where each `StepNavItem` has a label and optionally a url. |

**Example:**

```tsx
'use client'
import { type StepNavItem, useStepNav } from '@payloadcms/ui'
import { useEffect } from 'react'

export const MySetStepNavComponent: React.FC<{
nav: StepNavItem[]
}> = ({ nav }) => {
const { setStepNav } = useStepNav()

useEffect(() => {
setStepNav(nav)
}, [setStepNav, nav])

return null
}
```

0 comments on commit d8682f2

Please # to comment.