Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs][data grid] Revise the Data Grid getting started docs #15757

Merged
merged 44 commits into from
Jan 20, 2025
Merged
Show file tree
Hide file tree
Changes from 39 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
53481a9
init
mapache-salvaje Dec 5, 2024
839fb57
Merge branch 'master' into datagrid-gsd
mapache-salvaje Dec 19, 2024
32a6f8c
prettier
mapache-salvaje Dec 19, 2024
f2124ad
getting-started first pass
mapache-salvaje Dec 19, 2024
b99199c
nbsps
mapache-salvaje Dec 19, 2024
87ac014
revert out of scope change
mapache-salvaje Dec 19, 2024
aa63e17
broken links
mapache-salvaje Dec 19, 2024
2fe2f2a
Merge branch 'master' into datagrid-gsd
mapache-salvaje Jan 7, 2025
2d6e07a
one package to import
mapache-salvaje Jan 7, 2025
507d94d
overview
mapache-salvaje Jan 7, 2025
8c22a91
not also
mapache-salvaje Jan 7, 2025
d4554d8
copyedit popular features demo
mapache-salvaje Jan 7, 2025
aed9181
Merge branch 'master' into datagrid-gsd
mapache-salvaje Jan 9, 2025
7e28bcc
mapache-salvaje Jan 9, 2025
18adff3
merge master
mapache-salvaje Jan 9, 2025
19fd0b1
feature showcase copy
mapache-salvaje Jan 9, 2025
cec1654
restore api sections
mapache-salvaje Jan 9, 2025
a82ded8
gs to quickstart, success callout
mapache-salvaje Jan 9, 2025
0298584
move content from faq to perf, first pass at perf content
mapache-salvaje Jan 9, 2025
1725e46
performance page
mapache-salvaje Jan 9, 2025
bef6003
move content from faq
mapache-salvaje Jan 9, 2025
62a8e5b
introduce cells page
mapache-salvaje Jan 9, 2025
84bd7ea
remove faqs
mapache-salvaje Jan 9, 2025
1c2c060
cells page first pass
mapache-salvaje Jan 14, 2025
e8c1bb2
Merge branch 'master' into datagrid-gsd
mapache-salvaje Jan 14, 2025
620c689
mapache-salvaje Jan 14, 2025
1ce51e0
updates
mapache-salvaje Jan 14, 2025
2acfff1
revert out of scope changes
mapache-salvaje Jan 14, 2025
b916112
weird change
mapache-salvaje Jan 14, 2025
be63db1
Merge branch 'master' into datagrid-gsd
mapache-salvaje Jan 15, 2025
5d6cf31
rendercell
mapache-salvaje Jan 15, 2025
14e395a
cells page
mapache-salvaje Jan 15, 2025
11d3950
perf final? pass
mapache-salvaje Jan 15, 2025
93cf83b
remove line breaks
mapache-salvaje Jan 15, 2025
13a4c61
quickstart callout
mapache-salvaje Jan 15, 2025
498a950
overview and quickstart final pass
mapache-salvaje Jan 15, 2025
e0b8f6c
cells final pass
mapache-salvaje Jan 15, 2025
41a8ba0
revert out of scope charts changes
mapache-salvaje Jan 15, 2025
c7748be
Update docs/data/data-grid/cells/cells.md
mapache-salvaje Jan 15, 2025
889fd98
drop function in headers
mapache-salvaje Jan 15, 2025
31954e0
funtion formatting
mapache-salvaje Jan 16, 2025
74dd7fa
Merge branch 'master' into datagrid-gsd
mapache-salvaje Jan 16, 2025
a327d2e
perf page ale feedback
mapache-salvaje Jan 17, 2025
57b5158
Merge branch 'master' into datagrid-gsd
mapache-salvaje Jan 17, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/.link-check-errors.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
Broken links found by `docs:link-check` that exist:

- https://mui.com/x/react-data-grid/#premium-plan
- https://mui.com/x/react-data-grid/getting-started/#feature-comparison
- https://mui.com/x/react-date-pickers/fields/#accessible-dom-structure
70 changes: 70 additions & 0 deletions docs/data/data-grid/cells/cells.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Data Grid - Cells

<p class="description">Learn how to customize the rendered elements and values of a cell.</p>

## Customizing cells

The Data Grid provides several methods for customizing the rendered elements and values of a cell, including `renderCell()`, `valueGetter()`, and `valueFormatter()`.
This document describes the key differences and specific use cases for each.

### renderCell() function

Use the `renderCell()` function to render any element inside of a cell.
This is the only way to render a React component inside a cell, and also the only way to customize a cell's behavior—for example, by adding a click handler.

Though powerful, it's also expensive in terms of performance, so it should only be used as a last resort when there are no other means for implementing a specific use case.

Here's an example of a cell that uses `renderCell()` to render a button:

```tsx
const columns: GridColDef[] = [
{
field: 'date',
headerName: 'Year',
renderCell: (params: GridRenderCellParams<any, Date>) => (
<strong>
{params.value.getFullYear()}
<Button
variant="contained"
size="small"
style={{ marginLeft: 16 }}
tabIndex={params.hasFocus ? 0 : -1}
>
Open
</Button>
</strong>
),
},
];
```

See [Column definition—Rendering cells](/x/react-data-grid/column-definition/#rendering-cells) for more details.

### valueGetter() function

Use the `valueGetter()` function to derive a cell's value from the row data.
This is the the most performant way to customize the contents of a cell, and it does so without altering the row data itself.

Common use cases include:

- Transforming a value (for example, converting a decimal value to a percentage value)
- Deriving a value from multiple fields (for example, concatenating first name and last name)
- Deriving a value from a nested field (for example, `user.address.city`)

This function is also used internally in the Data Grid to filter, sort, and render (if `renderCell` or `valueFormatter` are not provided).

See [Column definition—Value getter](/x/react-data-grid/column-definition/#value-getter) for more details.

### valueFormatter() function

Use the `valueFormatter()` function to format a cell's value (without changing the underlying row data).

Common use cases include:

- Formatting a date to a custom display format
- Formatting a decimal value to a percentage and appending a `%` sign
- Formatting a boolean value to `Yes` or `No`

Unlike `valueGetter()`, this function only impacts rendering—_not_ internal calculations like filtering or sorting.

See [Column definition—value formatter](/x/react-data-grid/column-definition/#value-formatter) for more details.
64 changes: 23 additions & 41 deletions docs/data/data-grid/demo/PopularFeaturesDemo.js
Original file line number Diff line number Diff line change
Expand Up @@ -32,15 +32,14 @@ import LazyLoadingGrid from '../row-updates/LazyLoadingGrid';
import BasicGroupingDemo from '../column-groups/BasicGroupingDemo';
import EditingWithDatePickers from '../custom-columns/EditingWithDatePickers';
import CellSelectionGrid from '../cell-selection/CellSelectionRangeStyling';
import AddNewColumnMenuGrid from '../column-menu/AddNewColumnMenuGrid';
import HeaderFilteringDataGridPro from '../filtering/HeaderFilteringDataGridPro';
import ClipboardPaste from '../clipboard/ClipboardPaste';

export const featuresSet = [
{
id: 1,
name: 'Master detail',
description: 'A parent row with a collapsible child panel',
description: 'A parent row with a collapsible child panel.',
plan: 'Pro',
detailPage: '/master-detail/',
demo: <BasicDetailPanels />,
Expand All @@ -49,27 +48,25 @@ export const featuresSet = [
{
id: 2,
name: 'Inline editing',
description:
'Edit your data inside the cells by double-clicking or pressing Enter',
description: 'Edit data inside cells by double-clicking or pressing Enter.',
plan: 'Community',
detailPage: '/editing/',
demo: <EditingWithDatePickers />,
linkToCode: '/recipes-editing/#system-EditingWithDatePickers.tsx',
},
{
id: 3,
name: 'Column groups',
description: 'Group columns in a multi-level hierarchy',
name: 'Column grouping',
description: 'Group columns in a multi-level hierarchy.',
plan: 'Community',
detailPage: '/column-groups/',
newBadge: true,
demo: <BasicGroupingDemo />,
linkToCode: '/column-groups/#system-BasicGroupingDemo.tsx',
},
{
id: 4,
name: 'Lazy loading',
description: 'Easily paginate your rows and only fetch what you need',
description: 'Paginate rows and only fetch what you need.',
plan: 'Pro',
detailPage: '/pagination/',
demo: <LazyLoadingGrid />,
Expand All @@ -79,7 +76,7 @@ export const featuresSet = [
id: 5,
name: 'Save and restore state',
description:
'Save and restore internal state and configurations like active filters and sorting',
'Save and restore internal state and configurations like active filters and sorting.',
plan: 'Community',
detailPage: '/state/#save-and-restore-the-state',
demo: <RestoreStateInitialState />,
Expand All @@ -88,7 +85,7 @@ export const featuresSet = [
{
id: 6,
name: 'Row grouping',
description: 'Group rows with repeating column values',
description: 'Group rows with repeating column values.',
plan: 'Premium',
detailPage: '/row-grouping/',
demo: <RowGroupingInitialState />,
Expand All @@ -97,8 +94,7 @@ export const featuresSet = [
{
id: 7,
name: 'Excel export',
description:
'Easily export the rows in various file formats such as CSV, PDF or Excel',
description: 'Export rows in various file formats such as CSV, PDF or Excel.',
plan: 'Premium',
detailPage: '/export/#excel-export',
demo: <ExcelExport />,
Expand All @@ -107,16 +103,16 @@ export const featuresSet = [
{
id: 8,
name: 'Quick filter',
description: 'Use a single text input to filter multiple fields',
description: 'Use a single text input to filter multiple fields.',
plan: 'Community',
detailPage: '/filtering/quick-filter/',
demo: <QuickFilteringGrid />,
linkToCode: '/filtering/quick-filter/#system-QuickFilteringGrid.tsx',
},
{
id: 9,
name: 'Row reorder',
description: 'Drag and drop to reorder your data',
name: 'Row reordering',
description: 'Drag and drop to reorder data.',
plan: 'Pro',
detailPage: '/row-ordering/',
demo: <RowOrderingGrid />,
Expand All @@ -125,7 +121,7 @@ export const featuresSet = [
{
id: 10,
name: 'Column Pinning',
description: 'Pin your columns to the left or right',
description: 'Pin columns to the left or right.',
plan: 'Pro',
detailPage: '/column-pinning/',
demo: <BasicColumnPinning />,
Expand All @@ -134,7 +130,7 @@ export const featuresSet = [
{
id: 11,
name: 'Row pinning',
description: 'Pin your rows up or down',
description: 'Pin rows to the top or bottom of the Grid.',
plan: 'Pro',
detailPage: '/row-pinning/',
demo: <RowPinningWithPagination />,
Expand All @@ -143,7 +139,7 @@ export const featuresSet = [
{
id: 12,
name: 'Aggregation and Summary rows',
description: 'Set summary footer rows or inline summaries with row grouping',
description: 'Set summary footer rows or inline summaries with row grouping.',
plan: 'Premium',
detailPage: '/aggregation/',
demo: <AggregationRowGrouping />,
Expand All @@ -152,8 +148,7 @@ export const featuresSet = [
{
id: 13,
name: 'Column visibility',
description:
'Display different columns in different use cases by defining which columns are visible',
description: 'Display different columns for different use cases.',
plan: 'Community',
detailPage: '/column-visibility/',
demo: <ColumnSelectorGrid />,
Expand All @@ -162,7 +157,7 @@ export const featuresSet = [
{
id: 14,
name: 'Column virtualization',
description: 'High performance support for thousands of columns',
description: 'High-performance support for thousands of columns.',
plan: 'Community',
detailPage: '/virtualization/#column-virtualization',
demo: <ColumnVirtualizationGrid />,
Expand All @@ -171,15 +166,15 @@ export const featuresSet = [
{
id: 15,
name: 'Row virtualization',
description: 'High performance support for vast volume of data',
description: 'High-performance support for large volumes of data.',
plan: 'Pro',
detailPage: '/virtualization/#row-virtualization',
demo: <FullFeaturedDemo />,
},
{
id: 16,
name: 'Tree data',
description: 'Support rows with parent / child relationship',
description: 'Support rows with a parent/child relationship.',
plan: 'Pro',
detailPage: '/tree-data/',
demo: <TreeDataFullExample />,
Expand All @@ -189,44 +184,31 @@ export const featuresSet = [
id: 17,
name: 'Cell selection',
description:
'Allow users to select individual and multiple cells with mouse dragging and/or keyboard (using shift key)',
'Select one or more cells by dragging the mouse or using the Shift key.',
plan: 'Premium',
detailPage: '/cell-selection/',
demo: <CellSelectionGrid />,
linkToCode: '/cell-selection/#system-CellSelectionGrid.tsx',
newBadge: true,
},
{
id: 18,
name: 'Column menu',
description: 'More customization and improved design on v6',
plan: 'Community',
detailPage: '/column-menu/',
demo: <AddNewColumnMenuGrid />,
linkToCode: '/column-menu/#system-AddNewColumnMenuGrid.tsx',
newBadge: true,
},
{
id: 19,
name: 'Clipboard paste',
description:
'Copy and paste the selected cells and rows using the copy/paste keyboard shortcuts.',
'Copy and paste selected cells and rows using standard keyboard shortcuts.',
plan: 'Premium',
detailPage: '/clipboard/#clipboard-paste',
demo: <ClipboardPaste />,
linkToCode: '/clipboard/#system-ClipboardPaste.tsx',
newBadge: true,
},
{
id: 20,
id: 19,
name: 'Header filters',
description:
'Quickly accessible and customizable header filters to filter the data',
'Quickly accessible and customizable header filters to filter the data.',
plan: 'Pro',
detailPage: '/filtering/#header-filters',
demo: <HeaderFilteringDataGridPro />,
linkToCode: '/filtering/header-filters/#system-HeaderFilteringDataGridPro.tsx',
newBadge: true,
},
];

Expand Down Expand Up @@ -419,7 +401,7 @@ const columns = [
},
{
field: 'description',
headerName: 'Brief description',
headerName: 'Description',
groupable: false,
flex: 0.5,
minWidth: 120,
Expand Down
Loading
Loading