[docs] New page presenting the apiRef

docs/data/data-grid/api-object/UseGridApiContext.js

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import { DataGrid, GridToolbarContainer, useGridApiContext } from '@mui/x-data-grid';
+import { useDemoData } from '@mui/x-data-grid-generator';
+
+const CustomToolbar = () => {
+  const apiRef = useGridApiContext();
+
+  const handleGoToPage1 = () => apiRef.current.setPage(1);
+
+  return (
+    <GridToolbarContainer>
+      <Button onClick={handleGoToPage1}>Go to page 1</Button>
+    </GridToolbarContainer>
+  );
+};
+
+export default function UseGridApiContext() {
+  const { data } = useDemoData({
+    dataSet: 'Commodity',
+    rowLength: 100,
+    maxColumns: 6,
+  });
+
+  return (
+    <Box sx={{ height: 400, width: '100%' }}>
+      <DataGrid
+        {...data}
+        components={{
+          Toolbar: CustomToolbar,
+        }}
+        pageSize={10}
+      />
+    </Box>
+  );
+}

docs/data/data-grid/api-object/UseGridApiContext.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import { DataGrid, GridToolbarContainer, useGridApiContext } from '@mui/x-data-grid';
+import { useDemoData } from '@mui/x-data-grid-generator';
+
+const CustomToolbar = () => {
+  const apiRef = useGridApiContext();
+
+  const handleGoToPage1 = () => apiRef.current.setPage(1);
+
+  return (
+    <GridToolbarContainer>
+      <Button onClick={handleGoToPage1}>Go to page 1</Button>
+    </GridToolbarContainer>
+  );
+};
+
+export default function UseGridApiContext() {
+  const { data } = useDemoData({
+    dataSet: 'Commodity',
+    rowLength: 100,
+    maxColumns: 6,
+  });
+
+  return (
+    <Box sx={{ height: 400, width: '100%' }}>
+      <DataGrid
+        {...data}
+        components={{
+          Toolbar: CustomToolbar,
+        }}
+        pageSize={10}
+      />
+    </Box>
+  );
+}

docs/data/data-grid/api-object/UseGridApiContext.tsx.preview

@@ -0,0 +1,7 @@
+<DataGrid
+  {...data}
+  components={{
+    Toolbar: CustomToolbar,
+  }}
+  pageSize={10}
+/>

docs/data/data-grid/api-object/UseGridApiRef.js

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import Box from '@mui/material/Box';
+import { DataGridPro, useGridApiRef } from '@mui/x-data-grid-pro';
+import { useDemoData } from '@mui/x-data-grid-generator';
+
+export default function UseGridApiRef() {
+  const { data } = useDemoData({
+    dataSet: 'Commodity',
+    rowLength: 100,
+    maxColumns: 6,
+  });
+
+  const apiRef = useGridApiRef();
+
+  const handleGoToPage1 = () => apiRef.current.setPage(1);
+
+  return (
+    <Stack spacing={2} sx={{ width: '100%' }} alignItems="flex-start">
+      <Button onClick={handleGoToPage1}>Go to page 1</Button>
+      <Box sx={{ height: 400, width: '100%' }}>
+        <DataGridPro {...data} apiRef={apiRef} pagination pageSize={10} />
+      </Box>
+    </Stack>
+  );
+}

docs/data/data-grid/api-object/UseGridApiRef.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import Box from '@mui/material/Box';
+import { DataGridPro, useGridApiRef } from '@mui/x-data-grid-pro';
+import { useDemoData } from '@mui/x-data-grid-generator';
+
+export default function UseGridApiRef() {
+  const { data } = useDemoData({
+    dataSet: 'Commodity',
+    rowLength: 100,
+    maxColumns: 6,
+  });
+
+  const apiRef = useGridApiRef();
+
+  const handleGoToPage1 = () => apiRef.current.setPage(1);
+
+  return (
+    <Stack spacing={2} sx={{ width: '100%' }} alignItems="flex-start">
+      <Button onClick={handleGoToPage1}>Go to page 1</Button>
+      <Box sx={{ height: 400, width: '100%' }}>
+        <DataGridPro {...data} apiRef={apiRef} pagination pageSize={10} />
+      </Box>
+    </Stack>
+  );
+}

docs/data/data-grid/api-object/UseGridApiRef.tsx.preview

@@ -0,0 +1,4 @@
+<Button onClick={handleGoToPage1}>Go to page 1</Button>
+<Box sx={{ height: 400, width: '100%' }}>
+  <DataGridPro {...data} apiRef={apiRef} pagination pageSize={10} />
+</Box>

docs/data/data-grid/api-object/api-object.md

@@ -0,0 +1,81 @@
+---
+title: Data Grid - API object
+---
+
+# Data grid - API object
+
+<p class="description">Interact with the grid using its api.</p>
+
+## What is the API object ?
+
+The API object is an interface containing the state and all the methods needed to interact imperatively with the grid.
+
+You can find the list of all the available API methods on the [GridApi page](/x/api/data-grid/grid-api/).
+
+:::warning
+All the methods prefixed by `unstable_` are private.
+They should not be used by third party user and can be removed / renamed / reworked at any time.
+
+If you need to use a private method, please open a GitHub issue describing your use case.
+We will help you to achieve the same goal with public methods, or we will discuss making this specific method public.
+:::
+
+## How to use the API object ?
+
+The API object is accessible through the `apiRef` variable.
+Depending on where you are trying to access this variable, you will have to use either `useGridApiContext` or `useGridApiRef`.
+
+### Use it inside the grid
+
+If you need to access the api object inside component slots or inside renders (e.g: `renderCell`, `renderHeader`),
+you can use the `useGridApiContext` hook.
+
+```tsx
+const apiRef = useGridApiContext();
+
+<Button onClick={() => apiRef.current.setPage(1)}>Go to page 1</Button>;
+```
+
+:::info
+You don't have to initialize the API object using `useGridApiRef` to be able to it inside the grid components.
+:::
+
+{{"demo": "UseGridApiContext.js", "bg": "inline", "defaultCodeOpen": false}}
+
+### Use it outside the grid [<span class="plan-pro"></span>](https://mui.com/store/items/mui-x-pro/)
+
+When using the API object outside the grid components, you need to initialize it using the `useGridApiRef` hook.
+You can then pass it to the `apiRef` prop of the grid.
+
+```tsx
+const apiRef = useGridApiRef();
+
+<div>
+  <Button onClick={() => apiRef.current.setPage(1)}>Go to page 1</Button>
+  <DataGridPro apiRef={apiRef} {...other} />
+</div>;
+```
+
+:::warning
+The API object will be populated by the various plugins of the grid during the 1st render of our component.
+If you try to use it in the 1st render of your component, all the methods will be undefined.
+:::
+
+{{"demo": "UseGridApiRef.js", "bg": "inline", "defaultCodeOpen": false}}
+
+## Common use cases
+
+### Retrieve data from the state
+
+You can find a detailed example in the [State page](/x/react-data-grid/state/#access-the-state).
+
+### Listen to grid events
+
+You can find a detailed example in the [Events page](/x/react-data-grid/events/#subscribing-to-events).
+
+## API
+
+- [GridApi](/x/api/data-grid/grid-api/)
+- [DataGrid](/x/api/data-grid/data-grid/)
+- [DataGridPro](/x/api/data-grid/data-grid-pro/)
+- [DataGridPremium](/x/api/data-grid/data-grid-premium/)

docs/data/data-grid/components/components.md

@@ -39,10 +39,8 @@ The grid exposes two hooks to help you to access the grid data while overriding
 
 They can be used as below:
 
-- `useGridApiContext`: returns the `apiRef`.
-- `useGridSelector`: returns the result of a selector on the current state.
-
-More details about the selectors in the [State page](/x/react-data-grid/state/#access-the-state)
+- `useGridApiContext`: returns the `apiRef` (more details in the [API object page](/x/react-data-grid/api-object/#use-it-outside-the-grid)).
+- `useGridSelector`: returns the result of a selector on the current state (more details in the [State page](/x/react-data-grid/state/#access-the-state)).
 
 ```tsx
 function CustomPagination() {

docs/data/pages.ts

@@ -37,8 +37,6 @@ const pages: MuiPage[] = [
       { pathname: '/x/react-data-grid/filtering' },
       { pathname: '/x/react-data-grid/pagination' },
       { pathname: '/x/react-data-grid/selection' },
-      { pathname: '/x/react-data-grid/events' },
-      { pathname: '/x/react-data-grid/state' },
       { pathname: '/x/react-data-grid/export' },
       { pathname: '/x/react-data-grid/components' },
       { pathname: '/x/react-data-grid/style' },
@@ -64,6 +62,20 @@ const pages: MuiPage[] = [
           { pathname: '/x/react-data-grid/pivoting', title: 'Pivoting 🚧', plan: 'premium' },
         ],
       },
+      {
+        title: 'Advanced',
+        pathname: '/x/react-data-grid/api-object',
+        scopePathnames: [
+          '/x/react-data-grid/api-object',
+          '/x/react-data-grid/events',
+          '/x/react-data-grid/state',
+        ],
+        children: [
+          { pathname: '/x/react-data-grid/api-object', title: 'API object' },
+          { pathname: '/x/react-data-grid/events' },
+          { pathname: '/x/react-data-grid/state' },
+        ],
+      },
       {
         pathname: '/x/api/data-grid',
         title: 'API Reference',

docs/pages/x/react-data-grid/api-object.js

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import {
+  demos,
+  docs,
+  demoComponents,
+} from 'docsx/data/data-grid/api-object/api-object.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} disableAd />;
+}