docs: create row selection guide (#5226)

docs/config.json

@@ -368,6 +368,10 @@
           "to": "examples/vue/pagination",
           "label": "Pagination"
         },
+        {
+          "to": "examples/vue/row-selection",
+          "label": "Row Selection"
+        },
         {
           "to": "examples/vue/sorting",
           "label": "Sorting"

docs/guide/row-selection.md

@@ -6,9 +6,179 @@ title: Row Selection
 
 Want to skip to the implementation? Check out these examples:
 
-- [row-selection](../examples/react/row-selection)
-- [expanding](../examples/react/expanding)
+- [React row-selection](../examples/react/row-selection)
+- [Vue row-selection](../examples/vue/row-selection)
+- [React expanding](../examples/react/expanding)
 
 ## API
 
 [Row Selection API](../api/features/row-selection)
+
+## Guide
+
+The row selection feature keeps track of which rows are selected and allows you to toggle the selection of rows in a myriad of ways. Let's take a look at some common use cases.
+
+### Access Row Selection State
+
+The table instance already manages the row selection state for you (though as seen down below, it may be more convenient to manage the row selection state in your own scope). You can access the internal row selection state or the selected rows from a few APIs.
+
+- `getState().rowSelection` - returns the internal row selection state
+- `getSelectedRowModel()` - returns selected rows
+- `getFilteredSelectedRowModel()` - returns selected rows after filtering
+- `getGroupedSelectedRowModel()` - returns selected rows after grouping and sorting
+
+```ts
+console.log(table.getState().rowSelection) //get the row selection state - { 1: true, 2: false, etc... }
+console.log(table.getSelectedRowModel().rows) //get full client-side selected rows
+console.log(table.getFilteredSelectedRowModel().rows) //get filtered client-side selected rows
+console.log(table.getGroupedSelectedRowModel().rows) //get grouped client-side selected rows
+```
+
+> Note: If you are using `manualPagination`, be aware that the `getSelectedRowModel` API will only return selected rows on the current page because table row models can only generate rows based on the `data` that is passed in. Row selection state, however, can contain row ids that are not present in the `data` array just fine.
+
+### Manage Row Selection State
+
+Even though the table instance will already manage the row selection state for you, it is usually more convenient to manage the state yourself in order to have easy access to the selected row ids that you can use to make API calls or other actions.
+
+Use the `onRowSelectionChange` table option to hoist up the row selection state to your own scope. Then pass the row selection state back to the table instance using in the `state` table option.
+
+```ts
+const [rowSelection, setRowSelection] = useState<RowSelectionState>({}) //manage your own row selection state
+
+const table = useReactTable({
+  //...
+  onRowSelectionChange: setRowSelection, //hoist up the row selection state to your own scope
+  state: {
+    rowSelection, //pass the row selection state back to the table instance
+  },
+})
+```
+
+### Useful Row Ids
+
+By default, the row id for each row is simply the `row.index`. If you are using row selection features, you most likely want to use a more useful row identifier, since the row selection state is keyed by row id. You can use the `getRowId` table option to specify a function that returns a unique row id for each row.
+
+```ts
+const table = useReactTable({
+  //...
+  getRowId: row => row.uuid, //use the row's uuid from your database as the row id
+})
+```
+
+Now as rows are selected, the row selection state will look something like this:
+
+```json
+{
+  "13e79140-62a8-4f9c-b087-5da737903b76": true,
+  "f3e2a5c0-5b7a-4d8a-9a5c-9c9b8a8e5f7e": false
+  //...
+}
+```
+
+instead of this:
+
+```json
+{
+  "0": true,
+  "1": false
+  //...
+}
+```
+
+### Enable Row Selection Conditionally
+
+Row selection is enabled by default for all rows. To either enable row selection conditionally for certain rows or disable row selection for all rows, you can use the `enableRowSelection` table option which accepts either a boolean or a function for more granular control.
+
+```ts
+const table = useReactTable({
+  //...
+  enableRowSelection: row => row.original.age > 18, //only enable row selection for adults
+})
+```
+
+To enforce whether a row is selectable or not in your UI, you can use the `row.getCanSelect()` API for your checkboxes or other selection UI.
+
+### Single Row Selection
+
+By default, the table allows multiple rows to be selected at once. If, however, you only want to allow a single row to be selected at once, you can set the `enableMultiRowSelection` table option to `false` to disable multi-row selection, or pass in a function to disable multi-row selection conditionally for a row's sub-rows.
+
+This is useful for making tables that have radio buttons instead of checkboxes.
+
+```ts
+const table = useReactTable({
+  //...
+  enableMultiRowSelection: false, //only allow a single row to be selected at once
+  // enableMultiRowSelection: row => row.original.age > 18, //only allow a single row to be selected at once for adults
+})
+```
+
+### Sub-Row Selection
+
+By default, selecting a parent row will select all of its sub-rows. If you want to disable auto sub-row selection, you can set the `enableSubRowSelection` table option to `false` to disable sub-row selection, or pass in a function to disable sub-row selection conditionally for a row's sub-rows.
+
+```ts
+const table = useReactTable({
+  //...
+  enableSubRowSelection: false, //disable sub-row selection
+  // enableSubRowSelection: row => row.original.age > 18, //disable sub-row selection for adults
+})
+```
+
+### Render Row Selection UI
+
+TanStack table does not dictate how you should render your row selection UI. You can use checkboxes, radio buttons, or simply hook up click events to the row itself. The table instance provides a few APIs to help you render your row selection UI.
+
+#### Connect Row Selection APIs to Checkbox Inputs
+
+TanStack Table provides some handler functions that you can connect directly to your checkbox inputs to make it easy to toggle row selection. These function automatically call other internal APIs to update the row selection state and re-render the table.
+
+Use the `row.getToggleSelectedHandler()` API to connect to your checkbox inputs to toggle the selection of a row.
+
+Use the `table.getToggleAllRowsSelectedHandler()` or `table.getToggleAllPageRowsSelectedHandler` APIs to connect to your "select all" checkbox input to toggle the selection of all rows.
+
+If you need more granular control over these function handlers, you can always just use the `row.toggleSelected()` or `table.toggleAllRowsSelected()` APIs directly. Or you can even just call the `table.setRowSelection()` API to directly set the row selection state just as you would with any other state updater. These handler functions are just a convenience.
+
+```tsx
+const columns = [
+  {
+    id: 'select-col',
+    header: ({ table }) => (
+      <Checkbox
+        checked={table.getIsAllRowsSelected()}
+        indeterminate={table.getIsSomeRowsSelected()}
+        onChange={table.getToggleAllRowsSelectedHandler()} //or getToggleAllPageRowsSelectedHandler
+      />
+    ),
+    cell: ({ row }) => (
+      <Checkbox
+        checked={row.getIsSelected()}
+        disabled={!row.getCanSelect()}
+        onChange={row.getToggleSelectedHandler()}
+      />
+    ),
+  },
+  //... more column definitions...
+]
+```
+
+#### Connect Row Selection to Row Click Events
+
+If you want a simpler row selection UI, you can just hook up click events to the row itself. The `row.getToggleSelectedHandler()` API is also useful for this use case.
+
+```tsx
+<tbody>
+  {table.getRowModel().rows.map(row => {
+    return (
+      <tr
+        key={row.id}
+        className={row.getIsSelected() ? 'selected' : null}
+        onClick={row.getToggleSelectedHandler()}
+      >
+        {row.getVisibleCells().map(cell => {
+          return <td key={cell.id}>{/* */}</td>
+        })}
+      </tr>
+    )
+  })}
+</tbody>
+```

examples/react/expanding/src/main.tsx

@@ -264,7 +264,10 @@ function App() {
       <div>
         <button onClick={() => refreshData()}>Refresh Data</button>
       </div>
+      <label>Expanded State:</label>
       <pre>{JSON.stringify(expanded, null, 2)}</pre>
+      <label>Row Selection State:</label>
+      <pre>{JSON.stringify(table.getState().rowSelection, null, 2)}</pre>
     </div>
   )
 }

examples/react/row-selection/src/main.tsx

@@ -271,14 +271,6 @@ function App() {
           Refresh Data
         </button>
       </div>
-      <div>
-        <button
-          className="border rounded p-2 mb-2"
-          onClick={() => console.info('rowSelection', rowSelection)}
-        >
-          Log `rowSelection` state
-        </button>
-      </div>
       <div>
         <button
           className="border rounded p-2 mb-2"
@@ -292,6 +284,10 @@ function App() {
           Log table.getSelectedRowModel().flatRows
         </button>
       </div>
+      <div>
+        <label>Row Selection State:</label>
+        <pre>{JSON.stringify(table.getState().rowSelection, null, 2)}</pre>
+      </div>
     </div>
   )
 }