diff --git a/README.md b/README.md index b2e30d211bdc1..9e9cb4af10212 100644 --- a/README.md +++ b/README.md @@ -40,10 +40,10 @@ Get started in the [MUI X documentation](https://mui.com/x/introduction/). ### Installation -- [Data Grid installation](https://mui.com/x/react-data-grid/getting-started/#installation) -- [Date and Time Pickers installation](https://mui.com/x/react-date-pickers/getting-started/#installation) -- [Charts installation](https://mui.com/x/react-charts/getting-started/#installation) -- [Tree View installation](https://mui.com/x/react-tree-view/getting-started/#installation) +- [Data Grid installation](https://mui.com/x/react-data-grid/quickstart/#installation) +- [Date and Time Pickers installation](https://mui.com/x/react-date-pickers/quickstart/#installation) +- [Charts installation](https://mui.com/x/react-charts/quickstart/#installation) +- [Tree View installation](https://mui.com/x/react-tree-view/quickstart/#installation) ## Licensing diff --git a/docs/.link-check-errors.txt b/docs/.link-check-errors.txt index e5600de0a9a07..cfa8310011477 100644 --- a/docs/.link-check-errors.txt +++ b/docs/.link-check-errors.txt @@ -1,5 +1,12 @@ Broken links found by `docs:link-check` that exist: +- https://mui.com/x/react-charts/getting-started/ - https://mui.com/x/react-data-grid/#premium-plan +- https://mui.com/x/react-data-grid/getting-started/ - https://mui.com/x/react-data-grid/getting-started/#feature-comparison - https://mui.com/x/react-date-pickers/fields/#accessible-dom-structure +- https://mui.com/x/react-date-pickers/getting-started/ +- https://mui.com/x/react-date-pickers/quickstart/#date-and-time-types +- https://mui.com/x/react-tree-view/#rich-tree-view +- https://mui.com/x/react-tree-view/#simple-tree-view +- https://mui.com/x/react-tree-view/getting-started/ diff --git a/docs/data/charts/overview/overview.md b/docs/data/charts/overview/overview.md index 92f1d289714df..876a2d3dcfeca 100644 --- a/docs/data/charts/overview/overview.md +++ b/docs/data/charts/overview/overview.md @@ -17,20 +17,19 @@ MUI X Charts is a library of production-ready components for rendering charts w It uses [D3.js](https://d3js.org/) for data manipulation and SVGs for rendering. The components provide a high level of customization, with beautiful defaults as well as extensive configuration props and flexible composition options. -They also have access to all [MUI System](https://mui.com/system/getting-started/) tools such as theme overrides and the `sx` prop. +Theming features are designed to be frictionless when integrating with Material UI and other MUI X components, but they can also stand on their own and be customized to meet the needs of any design system. + +The Charts package is **open-core**: The Community version is MIT-licensed and free forever, while more advanced features require a Pro commercial license. +See [MUI X Licensing](/x/introduction/licensing/) for complete details. {{"demo": "ChartsOverviewDemo.js", "defaultCodeOpen": true}} ## All MUI X Charts -{{"component": "modules/components/ChartComponentsGrid.js"}} - -## Using this documentation +The MIT-licensed Community version of the Charts package covers the most common use cases for data visualization. +The Pro plan, denoted by the blue cube icon () throughout the documentation, expands on the Community version to support more complex visualizations. -Each Chart type has two accompanying documents: - -1. **Overview** – a general description of built-in features -2. **Demo** – a collection of custom examples +{{"component": "modules/components/ChartComponentsGrid.js"}} ## Supported features diff --git a/docs/data/charts/getting-started/Combining.js b/docs/data/charts/quickstart/Combining.js similarity index 100% rename from docs/data/charts/getting-started/Combining.js rename to docs/data/charts/quickstart/Combining.js diff --git a/docs/data/charts/getting-started/Combining.tsx b/docs/data/charts/quickstart/Combining.tsx similarity index 100% rename from docs/data/charts/getting-started/Combining.tsx rename to docs/data/charts/quickstart/Combining.tsx diff --git a/docs/data/charts/getting-started/SimpleCharts.js b/docs/data/charts/quickstart/SimpleCharts.js similarity index 100% rename from docs/data/charts/getting-started/SimpleCharts.js rename to docs/data/charts/quickstart/SimpleCharts.js diff --git a/docs/data/charts/getting-started/SimpleCharts.tsx b/docs/data/charts/quickstart/SimpleCharts.tsx similarity index 100% rename from docs/data/charts/getting-started/SimpleCharts.tsx rename to docs/data/charts/quickstart/SimpleCharts.tsx diff --git a/docs/data/charts/getting-started/SimpleCharts.tsx.preview b/docs/data/charts/quickstart/SimpleCharts.tsx.preview similarity index 100% rename from docs/data/charts/getting-started/SimpleCharts.tsx.preview rename to docs/data/charts/quickstart/SimpleCharts.tsx.preview diff --git a/docs/data/charts/getting-started/getting-started.md b/docs/data/charts/quickstart/quickstart.md similarity index 74% rename from docs/data/charts/getting-started/getting-started.md rename to docs/data/charts/quickstart/quickstart.md index 64eddde9f28f1..96648b5ee95b1 100644 --- a/docs/data/charts/getting-started/getting-started.md +++ b/docs/data/charts/quickstart/quickstart.md @@ -4,20 +4,24 @@ githubLabel: 'component: charts' packageName: '@mui/x-charts' --- -# Charts - Getting started +# Charts - Quickstart

Install the MUI X Charts package to start building React data visualization components.

## Installation -Run one of the following commands to install the free Community version or the paid Pro version of the MUI X Charts: +Install the Charts package that best suits your needs—Community or Pro: {{"component": "modules/components/ChartsInstallationInstructions.js"}} +### Peer dependencies + +#### Material UI + The Charts packages have a peer dependency on `@mui/material`. -If you're not already using it, install it with the following command: +If you're not already using it, install it now: @@ -35,6 +39,8 @@ yarn add @mui/material @emotion/react @emotion/styled +#### React + [`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) are also peer dependencies: @@ -48,16 +54,21 @@ yarn add @mui/material @emotion/react @emotion/styled ### Usage with D3 -To help folks using CommonJS, the `@mui/x-charts` package uses a vendored package named `@mui/x-charts-vendor` to access D3 libraries. +For those using CommonJS, the MUI X Charts provide a vendored package to access D3 libraries. You can import D3 functions from `@mui/x-charts-vendor/d3-scale`. ## Rendering Charts MUI X Charts can be rendered as _self-contained_ or _composable_ components. -[Self-contained components](#self-contained-charts) are simpler to get started with and are recommended for most common use cases; more complex visualization (such as combining Bar and Line Charts on a single plot) requires [custom composition](#composable-charts). +[Self-contained components](#self-contained-charts) are simpler to get started with and are recommended for most common use cases. +More complex visualization (such as combining Bar and Line Charts on a single plot) requires [custom composition](#composable-charts). ### Self-contained Charts +```tsx +import { BarChart } from '@mui/x-charts/BarChart'; +``` + Self-contained Chart components are imported and rendered as a single React component (such as `` or ``) which contains all of the necessary subcomponents. These components require a `series` prop describing the data to render, as well as a numerical value (rendered in pixels) for the `height` prop. @@ -72,8 +83,8 @@ Subcomponents include: - Axis components – to define the X and Y axes - Plot components – to create Bars, Lines, or any other Chart type -- Auxillary components - to add Tooltips, Highlights, and more -- Utilities - such as classes and types +- Auxiliary components – to add Tooltips, Highlights, and more +- Utilities – such as classes and types See the [Charts composition documentation](/x/react-charts/composition/) for complete details. @@ -81,42 +92,39 @@ The demo below shows how to use composition to create a custom Chart that combin {{"demo": "Combining.js"}} -## Chart layouts +### Chart layouts The layout of a Chart is defined by two main spaces: the plot area, and the outer margins. The `width` and `height` props define the dimensions of the SVG which is the root of the chart. -Within this SVG, the plot area (or drawing area) serves as the canvas for data visualization, where the lines, bars or other visual elements are rendered. +Within this SVG, the plot area (or drawing area) serves as the canvas for data visualization, where the lines, bars, or other visual elements are rendered. The size of the plot area is determined by the `margin = {top, bottom, left, right}` object which defines its outer margins inside the SVG. The outer margin space is where information like axes, titles, and legends are displayed. See the [Styling documentation](/x/react-charts/styling/#placement) for complete details. -## Server-side rendering - -The chart support server-side rendering under two conditions: +### Server-side rendering -1. The `width` and `height` props needs to be provided. -2. The animation should be disabled with the `skipAnimation` prop. +Charts support server-side rendering under two conditions: -The reason is that it is not possible to compute the SVG dimensions on the server, and the `skipAnimation` ensures that the animation is not in an "empty" state when first rendering. +1. `width` and `height` props must be provided – it's not possible to compute the SVG dimensions on the server. +2. Animations must be disabled with the `skipAnimation` prop – otherwise the animation will be in an empty state on first render. -## Axis management +### Axis management MUI X Charts take a flexible approach to axis management, with support for multiple axes and any combination of scales and ranges. - See the [Axis documentation](/x/react-charts/axis/) for complete details. ## TypeScript +### Theme augmentation + To benefit from [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users must import the following types. These types use module augmentation to extend the default theme structure. ```tsx -// only one import is necessary, -// from the version you're currently using. +// Pro users: add `-pro` suffix to package name import type {} from '@mui/x-charts/themeAugmentation'; -import type {} from '@mui/x-charts-pro/themeAugmentation'; const theme = createTheme({ components: { diff --git a/docs/data/common-concepts/custom-components/custom-components.md b/docs/data/common-concepts/custom-components/custom-components.md index e5605eb8ddc9d..878371aa51f38 100644 --- a/docs/data/common-concepts/custom-components/custom-components.md +++ b/docs/data/common-concepts/custom-components/custom-components.md @@ -8,7 +8,7 @@ A slot is a part of a component that can be [overridden](/x/common-concepts/cust Some of those slots allow you to provide your own UI primitives to the MUI X components. This is the role of all the `baseXXX` component on the Data Grid component (`baseButton`, `baseSelect`, ...). -These slots receive props that should be as generic as possible so that it is easy to interface any other design system. +These slots receive props that should be as generic as possible so they can integrate well with any other design system. Other slots allow you to override parts of the MUI X UI components with a custom UI built specifically for this component. This is the role of slots like `calendarHeader` on the `DateCalendar` component or `item` on the Rich Tree View component. diff --git a/docs/data/data-grid/custom-columns/custom-columns.md b/docs/data/data-grid/custom-columns/custom-columns.md index dd050b264956a..bc5fa95955500 100644 --- a/docs/data/data-grid/custom-columns/custom-columns.md +++ b/docs/data/data-grid/custom-columns/custom-columns.md @@ -33,7 +33,7 @@ In the demo below, we create a custom column type using the `GridColTypeDef` int By default, the Data Grid uses native browser inputs for editing `date` and `dateTime` columns. -While [MUI X Date / Time Pickers](/x/react-date-pickers/getting-started/) are not supported by the Data Grid out of the box yet, it is easy to integrate them by creating [custom edit components](/x/react-data-grid/editing/custom-edit-component/) and [custom filter operators](/x/react-data-grid/filtering/customization/#create-a-custom-operator). +While the [MUI X Date and Time Pickers](/x/react-date-pickers/) are not supported by the Data Grid out of the box yet, you can integrate them by creating [custom edit components](/x/react-data-grid/editing/custom-edit-component/) and [custom filter operators](/x/react-data-grid/filtering/customization/#create-a-custom-operator). The example below uses `@mui/x-date-pickers` for both `date` and `dateTime` column types: diff --git a/docs/data/data-grid/demo/FullFeaturedDemo.js b/docs/data/data-grid/features/FullFeaturedDemo.js similarity index 100% rename from docs/data/data-grid/demo/FullFeaturedDemo.js rename to docs/data/data-grid/features/FullFeaturedDemo.js diff --git a/docs/data/data-grid/demo/FullFeaturedDemo.tsx b/docs/data/data-grid/features/FullFeaturedDemo.tsx similarity index 100% rename from docs/data/data-grid/demo/FullFeaturedDemo.tsx rename to docs/data/data-grid/features/FullFeaturedDemo.tsx diff --git a/docs/data/data-grid/demo/PopularFeaturesDemo.js b/docs/data/data-grid/features/PopularFeaturesDemo.js similarity index 100% rename from docs/data/data-grid/demo/PopularFeaturesDemo.js rename to docs/data/data-grid/features/PopularFeaturesDemo.js diff --git a/docs/data/data-grid/demo/PopularFeaturesDemo.tsx b/docs/data/data-grid/features/PopularFeaturesDemo.tsx similarity index 100% rename from docs/data/data-grid/demo/PopularFeaturesDemo.tsx rename to docs/data/data-grid/features/PopularFeaturesDemo.tsx diff --git a/docs/data/data-grid/demo/demo.md b/docs/data/data-grid/features/features.md similarity index 100% rename from docs/data/data-grid/demo/demo.md rename to docs/data/data-grid/features/features.md diff --git a/docs/data/data-grid/overview/overview.md b/docs/data/data-grid/overview/overview.md index 5ea624c777378..a0866d2447ef0 100644 --- a/docs/data/data-grid/overview/overview.md +++ b/docs/data/data-grid/overview/overview.md @@ -19,10 +19,13 @@ It provides developers with an intuitive API for implementing complex use cases; The Grid's theming features are designed to be frictionless when integrating with Material UI and other MUI X components, but it can also stand on its own and be customized to meet the needs of any design system. The Data Grid is **open-core**: The Community version is MIT-licensed and free forever, while more advanced features require a Pro or Premium commercial license. - See [MUI X Licensing](/x/introduction/licensing/) for complete details. -## Community version +## Community version (free forever) + +```js +import { DataGrid } from '@mui/x-data-grid'; +``` The MIT-licensed Community version of the Data Grid is a more sophisticated implementation of the [Material UI Table](/material-ui/react-table/). @@ -32,8 +35,11 @@ It includes all of the main features listed in the navigation menu, such as edit ## Pro version [](/x/introduction/licensing/#pro-plan 'Pro plan') -The Pro plan expands on the Community version to support more complex use cases with features like advanced filtering, column pinning, column and row reordering, support for tree data, and virtualization to handle larger datasets. +```js +import { DataGridPro } from '@mui/x-data-grid-pro'; +``` +The Pro plan expands on the Community version to support more complex use cases with features like advanced filtering, column pinning, column and row reordering, support for tree data, and virtualization to handle larger datasets. Pro features are denoted by the blue cube icon () throughout the documentation. The demo below displays 31 columns and 100,000 rows—over three million cells in total: @@ -42,8 +48,11 @@ The demo below displays 31 columns and 100,000 rows—over three million cells i ## Premium version [](/x/introduction/licensing/#premium-plan 'Premium plan') -The Premium plan includes all Pro features as well as more advanced features for data analysis and large dataset management, such as row grouping with aggregation functions (like sum and average) and the ability to export to Excel files. +```js +import { DataGridPremium } from '@mui/x-data-grid-premium'; +``` +The Premium plan includes all Pro features as well as more advanced features for data analysis and large dataset management, such as row grouping with aggregation functions (like sum and average) and the ability to export to Excel files. Premium features are denoted by the golden cube icon () throughout the documentation. The demo below groups rows by commodity name, and uses an aggregation function to calculate the sum of quantities for each group and in total (displayed in a summary row). diff --git a/docs/data/data-grid/getting-started/Codesandbox.js b/docs/data/data-grid/quickstart/Codesandbox.js similarity index 100% rename from docs/data/data-grid/getting-started/Codesandbox.js rename to docs/data/data-grid/quickstart/Codesandbox.js diff --git a/docs/data/data-grid/getting-started/getting-started.md b/docs/data/data-grid/quickstart/quickstart.md similarity index 81% rename from docs/data/data-grid/getting-started/getting-started.md rename to docs/data/data-grid/quickstart/quickstart.md index e0087d9441d5b..c7726d1c6b21d 100644 --- a/docs/data/data-grid/getting-started/getting-started.md +++ b/docs/data/data-grid/quickstart/quickstart.md @@ -4,7 +4,7 @@ ## Installation -Run one of the following commands to install the MUI X Data Grid package that best suits your needs—the free Community version or the paid Pro or Premium version: +Install the Data Grid package that best suits your needs—Community, Pro, or Premium: @@ -13,11 +13,15 @@ Run one of the following commands to install the MUI X Data Grid package that b :::success Not sure which package to choose? You can start with the Community version and upgrade to Pro or Premium at any time. -Check out the [Feature showcase](/x/react-data-grid/demo/) for a list of features available in each package. +Check out the [Feature showcase](/x/react-data-grid/features/) for a list of features available in each package. ::: +### Peer dependencies + +#### Material UI + The Data Grid packages have a peer dependency on `@mui/material`. -If you're not already using it, install it with the following command: +If you're not already using it, install it now: @@ -35,6 +39,8 @@ yarn add @mui/material @emotion/react @emotion/styled +#### React + [`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) are also peer dependencies: @@ -46,11 +52,14 @@ yarn add @mui/material @emotion/react @emotion/styled }, ``` -## Quickstart +## Rendering a Data Grid + +### Import the component -Import the component that corresponds to the version you're using, along with the `GridRowsProp` and `GridColDef` utilities: +Import the Data Grid component that corresponds to the version you're using, along with the `GridRowsProp` and `GridColDef` utilities: ```js +// choose one import { DataGrid, GridRowsProp, GridColDef } from '@mui/x-data-grid'; import { DataGridPro, GridRowsProp, GridColDef } from '@mui/x-data-grid-pro'; import { DataGridPremium, GridRowsProp, GridColDef } from '@mui/x-data-grid-premium'; @@ -85,7 +94,7 @@ const columns: GridColDef[] = [ ]; ``` -### Render the Data Grid +### Render the component With the component and utilites imported, and rows and columns defined, you're now ready to render the Data Grid as shown below: @@ -117,6 +126,8 @@ export default function App() { ## TypeScript +### Theme augmentation + To benefit from [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users must import the following types. These types use module augmentation to extend the default theme structure. @@ -140,16 +151,17 @@ const theme = createTheme({ ## Using this documentation -### The useDemoData hook +### @mui/x-data-grid-generator + +**The `@mui/x-data-grid-generator` is a development-only package and should not be used in production.** +You can use it to create a reproduction of a bug or generate demo data in your development environment. +You should not rely on its API—it doesn't follow semver. -The `useDemoData` hook is a utility hook from the `@mui/x-data-grid-generator` package. -It contains columns definitions and generates random data for the Data Grid. -It is often used in our demos to provide realistic data without polluting the code with data generation logic. +### useDemoData hook -:::success -Looking for the column definitions and custom cell renderers from the `useDemoData` hook? -Check out the [Custom columns demo](/x/react-data-grid/custom-columns/#full-example) where you can copy them from the demo source code. -::: +The `useDemoData` hook is a utility hook from the `@mui/x-data-grid-generator` package, used in demos throughout this documentation to provide realistic data without polluting the code with data generation logic. +It contains column definitions and generates random data for the Data Grid. +For more details on these definitions and the custom cell renderers available, see the [custom columns demo](/x/react-data-grid/custom-columns/#full-example) where you can copy them from the demo source code. Here's how it's used: @@ -168,12 +180,6 @@ export default function Demo() { It comes with two datasets: `Commodity` and `Employee`. You can customize the data generation by passing the custom options of type [`UseDemoDataOptions`](https://github.com/mui/mui-x/blob/6aad22644ee710690b90dc2ac6bbafceb91fecf0/packages/x-data-grid-generator/src/hooks/useDemoData.ts#L29-L36). -:::error -`@mui/x-data-grid-generator` is a development-only package and should not be used in production. -You can use it to create a reproduction of a bug or generate demo data in your development environment. -You should not rely on its API—it doesn't follow semver. -::: - ## API - [DataGrid](/x/api/data-grid/data-grid/) diff --git a/docs/data/date-pickers/base-concepts/base-concepts.md b/docs/data/date-pickers/base-concepts/base-concepts.md index 37ee4a4c2c584..15d1e45193a84 100644 --- a/docs/data/date-pickers/base-concepts/base-concepts.md +++ b/docs/data/date-pickers/base-concepts/base-concepts.md @@ -147,71 +147,6 @@ For example, in a Time Picker, it allows you to choose the date of your value: {{"demo": "ReferenceDateExplicitTimePicker.js"}} -## TypeScript - -### Theme augmentation - -To benefit from the [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users need to import the following types. -Internally, it uses module augmentation to extend the default theme structure. - -```tsx -import type {} from '@mui/x-date-pickers/themeAugmentation'; -import type {} from '@mui/x-date-pickers-pro/themeAugmentation'; - -const theme = createTheme({ - components: { - MuiDatePicker: { - defaultProps: { - displayWeekNumber: true, - }, - }, - MuiDateRangeCalendar: { - styleOverrides: { - root: { - backgroundColor: '#f0f0f0', - }, - }, - }, - }, -}); -``` - -:::info -You don't have to import the theme augmentation from both `@mui/x-date-pickers` and `@mui/x-date-pickers-pro` when using `@mui/x-date-pickers-pro`. -Importing it from `@mui/x-date-pickers-pro` is enough. -::: - -### Typing of the date - -The Date and Time Pickers components are compatible with several date libraries -that use different formats to represent their dates -(`Date` object for `date-fns`, `daysjs.Dayjs` object for `days-js`, etc.). -To correctly type all the props that are date-related, the adapters override a global type named `PickerValidDate` -to allow the usage of their own date format. -This allows TypeScript to throw an error if you try to pass `value={new Date()}` to a component using `AdapterDayjs` for instance. - -If you are not sure your adapter is set up correctly to infer the type of date-related props, you can import the `PickerValidDate` type and check its current value. - -If its equal to the format used by your date library, then you don't have to do anything: - -PickerValidDate correctly configured - -If it's equal to `any`, you can fix it by manually importing the adapter in some file of your project as show below: - -PickerValidDate not correctly configured - -```ts -// Replace `AdapterDayjs` with the adapter you are using. -import type {} from '@mui/x-date-pickers/AdapterDayjs'; -``` - -:::info -Before version 7.19.0, TypeScript was throwing an error such as `DesktopDatePickerProps error Type 'Date' does not satisfy the constraint 'never'` -when you were not importing the adapter in the same TypeScript project as the rest of your codebase. - -The fix described above should also solve the problem. -::: - ## Testing caveats ### Responsive components diff --git a/docs/data/date-pickers/date-picker/date-picker.md b/docs/data/date-pickers/date-picker/date-picker.md index f702279ebb37d..d7b5130f1b930 100644 --- a/docs/data/date-pickers/date-picker/date-picker.md +++ b/docs/data/date-pickers/date-picker/date-picker.md @@ -65,6 +65,15 @@ Responsive components can suffer some inconsistencies between testing environmen Please refer to [this section](/x/react-date-pickers/base-concepts/#testing-caveats) for solutions. ::: +### Keyboard Date Picker (legacy) + +The current implementation of the Date Picker component replaces the experimental Keyboard Date Picker from Material UI. +See the [migration documentation](/material-ui/migration/pickers-migration/#imports) for more information. + +For accessibility, all Picker components accept keyboard inputs. +If your use case only calls for keyboard editing, you can use Field components: the Date Picker component can be edited via input or a calendar, whereas the Date Field can only be edited via input. +See the [Fields documentation](/x/react-date-pickers/fields/) for more details. + ## Form props The component can be disabled or read-only. diff --git a/docs/data/date-pickers/faq/faq.md b/docs/data/date-pickers/faq/faq.md deleted file mode 100644 index b3be2015f249e..0000000000000 --- a/docs/data/date-pickers/faq/faq.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -productId: x-date-pickers -title: Frequently Asked Questions - Date and Time pickers -githubLabel: 'component: pickers' -packageName: '@mui/x-date-pickers' ---- - -# Frequently asked questions - -

Can't find what you are looking for? The FAQ section has answers to some of the most frequent questions and challenges.

- -If you still have trouble, you can refer to the [support page](/x/introduction/support/). - -## What is the DemoContainer and DemoItem? - -The `` is an internal component used together with the `` to display multiple components in a consistent layout throughout the demos. - -This helps avoid the repeated use of layout components, such as `` or ``, while keeping the code minimal and clear, and allowing readers to focus on what is important - the demo itself. - -:::warning -You should never use these components in your application. -::: - -## Why is the KeyboardDatePicker not supported anymore? - -It has been replaced with the `DatePicker` component, please refer to the [migration documentation](/material-ui/migration/pickers-migration/#imports) for more information. - -All versions of the date and time pickers implement keyboard input for accessibility and also allow editing through the UI. Depending on your use case, you may only need keyboard editing, in which case you can use the date and time field components. - -For instance, `DatePicker` allows for editing both via input and a calendar, while `DateField` only allows for editing via input. You can read more about the different types of components on the [base concepts page](/x/react-date-pickers/base-concepts/#other-components). - -For more information about the fields, you can refer to the [field components page](/x/react-date-pickers/fields/). diff --git a/docs/data/date-pickers/getting-started/getting-started.md b/docs/data/date-pickers/getting-started/getting-started.md deleted file mode 100644 index c3a703efd7b44..0000000000000 --- a/docs/data/date-pickers/getting-started/getting-started.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -productId: x-date-pickers -title: Date and Time Pickers - Getting started -packageName: '@mui/x-date-pickers' -githubLabel: 'component: pickers' -materialDesign: https://m2.material.io/components/date-pickers -waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/ ---- - -# Date and Time Pickers - Getting started - -

Install the Date and Time Pickers package and set up your date library to start building.

- -## Installation - -Install the base package (which can either be the free Community version or the paid Pro version) along with a required third-party date library. -The Pickers currently support [Day.js](https://day.js.org/), [date-fns](https://date-fns.org/), [Luxon](https://moment.github.io/luxon/#/), and [Moment.js](https://momentjs.com/). - -Choose your packages and manager through the toggles below, then run the commands as provided to install: - - - -{{"component": "modules/components/PickersInstallationInstructions.js"}} - -:::success -Not sure which date library to choose? -If you're starting from scratch with no other date libraries in your app, we recommend Day.js because of its small bundle size. -::: - -### Peer dependencies - -#### Material UI - -The Date and Time Pickers have a peer dependency on `@mui/material`. -If you're not already using it, install it with the following command: - - - -```bash npm -npm install @mui/material @emotion/react @emotion/styled -``` - -```bash pnpm -pnpm add @mui/material @emotion/react @emotion/styled -``` - -```bash yarn -yarn add @mui/material @emotion/react @emotion/styled -``` - - - -#### React - - - -[`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) are also peer dependencies: - -```json -"peerDependencies": { - "react": "^17.0.0 || ^18.0.0 || ^19.0.0", - "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0" -}, -``` - -## Date library adapter setup - -To integrate your chosen date library with the Date and Time Pickers, you'll need to plug the corresponding adapter into a `LocalizationProvider` that wraps your Picker components. - -Adapters are provided for each of the supported libraries, and all are exported by both `@mui/x-date-pickers` and `@mui/x-date-pickers-pro`—for example,`AdapterDayjs`, which is used throughout this documentation for [Day.js](https://day.js.org/) integration: - -```tsx -import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs'; -import { AdapterDayjs } from '@mui/x-date-pickers-pro/AdapterDayjs'; -``` - -### LocalizationProvider - -The `LocalizationProvider` component is exported by both `@mui/x-date-pickers` and `@mui/x-date-pickers-pro`: - -```tsx -import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider'; -import { LocalizationProvider } from '@mui/x-date-pickers-pro/LocalizationProvider'; -``` - -:::warning -For practical purposes, each demo in the documentation has its own `LocalizationProvider` wrapper. -**We _do not_ recommend reproducing this pattern as-is.** -For almost all use cases, you should wrap your entire app with a single `LocalizationProvider` to avoid repeating boilerplate code in multiple places. -::: - -{{"component": "modules/components/PickersRenderingInstructions.js"}} - -:::info -To use the Date and Time Pickers with a custom locale, see [Date and format localization](/x/react-date-pickers/adapters-locale/). -::: - -## Render your first component - -To confirm that everything is set up correctly, try rendering a basic Date Picker component: - -{{"demo": "FirstComponent.js"}} diff --git a/docs/data/date-pickers/getting-started/FirstComponent.js b/docs/data/date-pickers/quickstart/FirstComponent.js similarity index 100% rename from docs/data/date-pickers/getting-started/FirstComponent.js rename to docs/data/date-pickers/quickstart/FirstComponent.js diff --git a/docs/data/date-pickers/getting-started/FirstComponent.tsx b/docs/data/date-pickers/quickstart/FirstComponent.tsx similarity index 100% rename from docs/data/date-pickers/getting-started/FirstComponent.tsx rename to docs/data/date-pickers/quickstart/FirstComponent.tsx diff --git a/docs/data/date-pickers/getting-started/FirstComponent.tsx.preview b/docs/data/date-pickers/quickstart/FirstComponent.tsx.preview similarity index 100% rename from docs/data/date-pickers/getting-started/FirstComponent.tsx.preview rename to docs/data/date-pickers/quickstart/FirstComponent.tsx.preview diff --git a/docs/data/date-pickers/getting-started/MaterialUIPickers.tsx.preview b/docs/data/date-pickers/quickstart/MaterialUIPickers.tsx.preview similarity index 100% rename from docs/data/date-pickers/getting-started/MaterialUIPickers.tsx.preview rename to docs/data/date-pickers/quickstart/MaterialUIPickers.tsx.preview diff --git a/docs/data/date-pickers/quickstart/quickstart.md b/docs/data/date-pickers/quickstart/quickstart.md new file mode 100644 index 0000000000000..416ba65271fdb --- /dev/null +++ b/docs/data/date-pickers/quickstart/quickstart.md @@ -0,0 +1,180 @@ +--- +productId: x-date-pickers +title: Date and Time Pickers - Quickstart +packageName: '@mui/x-date-pickers' +githubLabel: 'component: pickers' +materialDesign: https://m2.material.io/components/date-pickers +waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/ +--- + +# Date and Time Pickers - Quickstart + +

Install the MUI X Date and Time Pickers package and set up your date library to start building.

+ +## Installation + +Install the Date and Time Pickers package that best suits your needs—Community or Pro—along with one of the supported third-party date libraries. +The Pickers currently support [Day.js](https://day.js.org/), [date-fns](https://date-fns.org/), [Luxon](https://moment.github.io/luxon/#/), and [Moment.js](https://momentjs.com/). + +Choose your packages and manager through the toggles below, then run the commands as provided to install: + + + +{{"component": "modules/components/PickersInstallationInstructions.js"}} + +:::success +Not sure which date library to choose? +If you're starting from scratch with no other date libraries in your app, we recommend [Day.js](https://day.js.org/) because of its small bundle size. +::: + +### Peer dependencies + +#### Material UI + +The Date and Time Pickers have a peer dependency on `@mui/material`. +If you're not already using it, install it now: + + + +```bash npm +npm install @mui/material @emotion/react @emotion/styled +``` + +```bash pnpm +pnpm add @mui/material @emotion/react @emotion/styled +``` + +```bash yarn +yarn add @mui/material @emotion/react @emotion/styled +``` + + + +#### React + + + +[`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) are also peer dependencies: + +```json +"peerDependencies": { + "react": "^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0" +}, +``` + +## Rendering a Date Picker + +### Import the component + +Import a Date Picker component and the Localization Provider: + +```js +import { DatePicker } from '@mui/x-date-pickers/DatePicker'; +import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider'; +``` + +Next, import the adapter that corresponds to your chosen date library. +Adapters are provided for all supported libraries in both versions of the package. +The snippet below imports `AdapterDayjs`, which is used throughout this documentation for Day.js integration. + +```tsx +import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs'; +``` + +### Integrate provider and adapter + +To integrate your chosen date library with the Date Pickers, wrap your app with the Localization Provider and pass the adapter to the Provider's `dateAdapter` prop as shown below: + +{{"component": "modules/components/PickersRenderingInstructions.js"}} + +:::info +To use the Date and Time Pickers with a custom locale, see [Date and format localization](/x/react-date-pickers/adapters-locale/). +::: + +### Render the component + +With the component, adapter, and provider properly configured, you're now ready to render a Date Picker as shown below: + +```tsx +import * as React from 'react'; +import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs'; +import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider'; +import { DatePicker } from '@mui/x-date-pickers/DatePicker'; + +export default function App() { + return ( + + + + ); +} +``` + +{{"demo": "FirstComponent.js"}} + +## TypeScript + +### Theme augmentation + +To benefit from [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users must import the following types. +These types use module augmentation to extend the default theme structure. + +```tsx +// Pro users: add `-pro` suffix to package name +import type {} from '@mui/x-date-pickers/themeAugmentation'; + +const theme = createTheme({ + components: { + MuiDatePicker: { + defaultProps: { + displayWeekNumber: true, + }, + }, + MuiDateRangeCalendar: { + styleOverrides: { + root: { + backgroundColor: '#f0f0f0', + }, + }, + }, + }, +}); +``` + +### Date value types + +The Date and Time Pickers are compatible with several date libraries that each use different formats to represent their dates. +To correctly type all date-related props, the adapters override a global type named `PickerValidDate` to allow for the formatting of their corresponding libraries. +As a result, TypeScript will throw an error if you try to pass the wrong kind of value to the date library. + +To determine whether your adapter is set up correctly, you can import the `PickerValidDate` type from `@mui/x-date-pickers/models` and check its current value. +If the type matches your chosen date library then it's correctly configured: + +PickerValidDate correctly configured + +If the type is `any`, you can fix this by manually importing the adapter's types directly into your project as shown below: + +```ts +// replace `AdapterDayjs` with the adapter you're using +import type {} from '@mui/x-date-pickers/AdapterDayjs'; +``` + +:::info +Before version 7.19.0, TypeScript would throw the following error if you didn't import the adapter in the same TypeScript project as the rest of your codebase: `DesktopDatePickerProps error Type 'Date' does not satisfy the constraint 'never'`. +The solution described above should resolve this. +::: + +## Using this documentation + +### Localization Provider + +For practical purposes, each demo in this documentation has its own Localization Provider wrapper. +**You should not reproduce this pattern as-is.** +For almost all use cases, you should wrap your entire app with a single Localization Provider to avoid repeating boilerplate code in multiple places. + +### Demo Container and Demo Item + +Throughout this documentation, the internal components `` and `` are used in demos to display multiple components with a consistent layout. +**You should never use these components in your application.** +This helps avoid the repeated use of layout components such as `` or ``, which would otherwise add irrelevant clutter to demos meant to illustrate specific features. diff --git a/docs/data/introduction/support/support.md b/docs/data/introduction/support/support.md index f965797405e05..d4d76894ac7ff 100644 --- a/docs/data/introduction/support/support.md +++ b/docs/data/introduction/support/support.md @@ -31,7 +31,7 @@ You have a few possible options to provide it: You can browse the documentation, find an example close to your use case, and then open it in a live editor: - + Forking an example @@ -40,10 +40,10 @@ You can browse the documentation, find an example close to your use case, and th -- [Data Grid](/x/react-data-grid/#community-version) -- [Date Pickers](/x/react-date-pickers/getting-started/#render-your-first-component) -- [Charts](/x/react-charts/getting-started/#self-contained-charts) -- [Tree View](/x/react-tree-view/#simple-tree-view) +- [Data Grid](/x/react-data-grid/#community-version-free-forever) +- [Date Pickers](/x/react-date-pickers/quickstart/#render-the-component) +- [Charts](/x/react-charts/quickstart/#self-contained-charts) +- [Tree View](/x/react-tree-view/) #### Use starter templates diff --git a/docs/data/migration/migration-pickers-lab/migration-pickers-lab.md b/docs/data/migration/migration-pickers-lab/migration-pickers-lab.md index 7e7190991b9a4..1de72e4ea8f37 100644 --- a/docs/data/migration/migration-pickers-lab/migration-pickers-lab.md +++ b/docs/data/migration/migration-pickers-lab/migration-pickers-lab.md @@ -101,7 +101,7 @@ Which will transform the imports like this: ``` Components of the Community plan such as `` can be imported from both `@mui/x-date-pickers-pro` and `@mui/x-date-pickers`. -[Date adapters](/x/react-date-pickers/getting-started/#installation) such as `AdapterDayjs` can only be imported from `@mui/x-date-pickers/[adapterName]`. +[Date adapters](/x/react-date-pickers/quickstart/#installation) such as `AdapterDayjs` can only be imported from `@mui/x-date-pickers/[adapterName]`. ### 3. Handle breaking changes introduced in alpha diff --git a/docs/data/migration/migration-pickers-v5/migration-pickers-v5.md b/docs/data/migration/migration-pickers-v5/migration-pickers-v5.md index 7985a701eb1bb..762a634f64117 100644 --- a/docs/data/migration/migration-pickers-v5/migration-pickers-v5.md +++ b/docs/data/migration/migration-pickers-v5/migration-pickers-v5.md @@ -152,7 +152,7 @@ const theme = createTheme({ ``` :::success -If you are using TypeScript, please make sure to add the [theme augmentation](/x/react-date-pickers/base-concepts/#typescript) to your project. +If you are using TypeScript, please make sure to add the [theme augmentation](/x/react-date-pickers/quickstart/#typescript) to your project. ::: ### Remove the keyboard view diff --git a/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md b/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md index 94e420e02781c..167401fa6c8eb 100644 --- a/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md +++ b/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md @@ -300,7 +300,7 @@ All the date-related props are now strictly typed to only accept the date format (`Date` object for `date-fns`, `daysjs.Dayjs` object for `days-js`, etc.). :::info -See [Base concepts—Typing of the date](/x/react-date-pickers/base-concepts/#typing-of-the-date) for more details. +See [Date and time types](/x/react-date-pickers/quickstart/#date-and-time-types) for more details. ::: ## Field components diff --git a/docs/data/pages.ts b/docs/data/pages.ts index 5def15ccecfdc..91f1c988be1a5 100644 --- a/docs/data/pages.ts +++ b/docs/data/pages.ts @@ -32,8 +32,8 @@ const pages: MuiPage[] = [ title: 'Data Grid', children: [ { pathname: '/x/react-data-grid', title: 'Overview' }, - { pathname: '/x/react-data-grid/getting-started', title: 'Quickstart' }, - { pathname: '/x/react-data-grid/demo', title: 'Feature showcase' }, + { pathname: '/x/react-data-grid/quickstart' }, + { pathname: '/x/react-data-grid/features' }, { pathname: '/x/react-data-grid/main-features', subheader: 'Main features', @@ -264,9 +264,8 @@ const pages: MuiPage[] = [ title: 'Date and Time Pickers', children: [ { pathname: '/x/react-date-pickers', title: 'Overview' }, - { pathname: '/x/react-date-pickers/getting-started' }, + { pathname: '/x/react-date-pickers/quickstart', title: 'Quickstart' }, { pathname: '/x/react-date-pickers/base-concepts' }, - { pathname: '/x/react-date-pickers/faq', title: 'FAQs' }, { pathname: '/x/react-date-pickers-components', subheader: 'Components', @@ -421,7 +420,7 @@ const pages: MuiPage[] = [ title: 'Charts', children: [ { pathname: '/x/react-charts', title: 'Overview' }, - { pathname: '/x/react-charts/getting-started' }, + { pathname: '/x/react-charts/quickstart', title: 'Quickstart' }, { pathname: '/x/react-chart-components', subheader: 'Components', @@ -533,7 +532,7 @@ const pages: MuiPage[] = [ title: 'Tree View', children: [ { pathname: '/x/react-tree-view', title: 'Overview' }, - { pathname: '/x/react-tree-view/getting-started' }, + { pathname: '/x/react-tree-view/quickstart', title: 'Quickstart' }, { pathname: '/x/react-tree-view/simple-tree-view', subheader: 'Simple Tree View', diff --git a/docs/data/tree-view/getting-started/getting-started.md b/docs/data/tree-view/getting-started/getting-started.md deleted file mode 100644 index d45b06955911f..0000000000000 --- a/docs/data/tree-view/getting-started/getting-started.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -productId: x-tree-view -title: Tree View - Getting started -components: SimpleTreeView, RichTreeView, TreeItem -packageName: '@mui/x-tree-view' -githubLabel: 'component: tree view' -waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/ ---- - -# Tree View - Getting Started - -

Get started with the Tree View. Install the package, configure your application and start using the components.

- -## Installation - -Using your favorite package manager, install `@mui/x-tree-view-pro` for the commercial version, or `@mui/x-tree-view` for the free community version. - - - -{{"component": "modules/components/TreeViewInstallationInstructions.js"}} - -The Tree View package has a peer dependency on `@mui/material`. -If you are not already using it in your project, you can install it with: - - - -```bash npm -npm install @mui/material @emotion/react @emotion/styled -``` - -```bash pnpm -pnpm add @mui/material @emotion/react @emotion/styled -``` - -```bash yarn -yarn add @mui/material @emotion/react @emotion/styled -``` - - - - - -Please note that [react](https://www.npmjs.com/package/react) and [react-dom](https://www.npmjs.com/package/react-dom) are peer dependencies too: - -```json -"peerDependencies": { - "react": "^17.0.0 || ^18.0.0 || ^19.0.0", - "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0" -}, -``` - -### Style engine - -Material UI is using [Emotion](https://emotion.sh/docs/introduction) as a styling engine by default. If you want to use [`styled-components`](https://styled-components.com/) instead, run: - - -```bash npm -npm install @mui/styled-engine-sc styled-components -``` - -```bash pnpm -pnpm add @mui/styled-engine-sc styled-components -``` - -```bash yarn -yarn add @mui/styled-engine-sc styled-components -``` - - - -Take a look at the [Styled engine guide](/material-ui/integrations/styled-components/) for more information about how to configure `styled-components` as the style engine. - -## Render your first component - -To make sure that everything is set up correctly, try rendering a Simple Tree View component: - -{{"demo": "FirstComponent.js"}} - -## Accessibility - -(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) - -The component follows the WAI-ARIA authoring practices. - -To have an accessible Tree View you must use `aria-labelledby` -or `aria-label` to reference or provide a label on the TreeView, -otherwise, screen readers will announce it as "tree", making it hard to understand the context of a specific tree item. - -## TypeScript - -In order to benefit from the [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users need to import the following types. -Internally, it uses module augmentation to extend the default theme structure. - -```tsx -import type {} from '@mui/x-tree-view/themeAugmentation'; - -const theme = createTheme({ - components: { - MuiRichTreeView: { - styleOverrides: { - root: { - backgroundColor: 'red', - }, - }, - }, - }, -}); -``` diff --git a/docs/data/tree-view/overview/TreeViewOverviewDemo.js b/docs/data/tree-view/overview/TreeViewOverviewDemo.js new file mode 100644 index 0000000000000..55561550c5293 --- /dev/null +++ b/docs/data/tree-view/overview/TreeViewOverviewDemo.js @@ -0,0 +1,30 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; +import { TreeItem } from '@mui/x-tree-view/TreeItem'; + +export default function TreeViewOverviewDemo() { + return ( + + + + + + + + + + + + + + + + + + + + + + ); +} diff --git a/docs/data/tree-view/overview/TreeViewOverviewDemo.tsx b/docs/data/tree-view/overview/TreeViewOverviewDemo.tsx new file mode 100644 index 0000000000000..55561550c5293 --- /dev/null +++ b/docs/data/tree-view/overview/TreeViewOverviewDemo.tsx @@ -0,0 +1,30 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; +import { TreeItem } from '@mui/x-tree-view/TreeItem'; + +export default function TreeViewOverviewDemo() { + return ( + + + + + + + + + + + + + + + + + + + + + + ); +} diff --git a/docs/data/tree-view/overview/overview.md b/docs/data/tree-view/overview/overview.md index e1c49a7e2bd69..668cd1c33803b 100644 --- a/docs/data/tree-view/overview/overview.md +++ b/docs/data/tree-view/overview/overview.md @@ -8,36 +8,40 @@ packageName: '@mui/x-tree-view' # MUI X Tree View -

The Tree View component lets users navigate hierarchical lists of data with nested levels that can be expanded and collapsed.

+

The Tree View lets users navigate hierarchical lists of data with nested levels that can be expanded and collapsed.

{{"component": "@mui/docs/ComponentLinkHeader"}} -## Available components +## Overview -The MUI X Tree View package exposes two different versions of the component: +The MUI X Tree View provides all of the functionality necessary to build a hierarchical list of expandable and collapsible items. +The Tree View's theming features are designed to be frictionless when integrating with Material UI and other MUI X components, but it can also stand on its own and be customized to meet the needs of any design system. -### Simple Tree View +The Tree View is **open-core**: The Community version is MIT-licensed and free forever, while more advanced features require a Pro commercial license. +See [MUI X Licensing](/x/introduction/licensing/) for complete details. -```jsx -import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; -``` +The demo below shows how to render a Simple Tree View—try clicking on an item to see how it expands and collapses: -The simple version of the Tree View component receives its items as JSX children. -This is the recommended version for hardcoded items. +{{"demo": "TreeViewOverviewDemo.js", "defaultCodeOpen": true}} -{{"demo": "BasicSimpleTreeView.js"}} +## Community version (free forever) -### Rich Tree View +```js +import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; +``` -```jsx +```js import { RichTreeView } from '@mui/x-tree-view/RichTreeView'; ``` -The rich version of the Tree View component receives its items dynamically from an external data source. -This is the recommended version for larger trees, as well as those that require more advanced features like editing and virtualization. +The MIT-licensed Community version of the Tree View covers the most common use cases. +Proceed to the [Quickstart guide](/x/react-tree-view/quickstart/) to learn more about the differences between the Simple and Rich Tree View components. + +## Pro version [](/x/introduction/licensing/#pro-plan 'Pro plan') -{{"demo": "BasicRichTreeView.js"}} +```js +import { RichTreeViewPro } from '@mui/x-tree-view-pro/RichTreeViewPro'; +``` -:::info -At the moment, the Simple and Rich Tree Views are similar in terms of feature support. But as the component grows, you can expect to see the more advanced ones appear primarily on the Rich Tree View. -::: +The Pro version of the Rich Tree View expands on the Community version by providing [drag-and-drop reordering](/x/react-tree-view/rich-tree-view/ordering/) functionality in addition to all other features. +Pro features are denoted by the blue cube icon () throughout the documentation. diff --git a/docs/data/tree-view/quickstart/BasicRichTreeView.js b/docs/data/tree-view/quickstart/BasicRichTreeView.js new file mode 100644 index 0000000000000..1756aba06d123 --- /dev/null +++ b/docs/data/tree-view/quickstart/BasicRichTreeView.js @@ -0,0 +1,48 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; + +import { RichTreeView } from '@mui/x-tree-view/RichTreeView'; + +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' }, + ], + }, + { + id: 'charts', + label: 'Charts', + children: [ + { id: 'charts-community', label: '@mui/x-charts' }, + { id: 'charts-pro', label: '@mui/charts-pro' }, + ], + }, + { + id: 'tree-view', + label: 'Tree View', + children: [ + { id: 'tree-view-community', label: '@mui/x-tree-view' }, + { id: 'tree-view-pro', label: '@mui/x-tree-view-pro' }, + ], + }, +]; + +export default function BasicRichTreeView() { + return ( + + + + ); +} diff --git a/docs/data/tree-view/quickstart/BasicRichTreeView.tsx b/docs/data/tree-view/quickstart/BasicRichTreeView.tsx new file mode 100644 index 0000000000000..0cb55d01c05a1 --- /dev/null +++ b/docs/data/tree-view/quickstart/BasicRichTreeView.tsx @@ -0,0 +1,48 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import { TreeViewBaseItem } from '@mui/x-tree-view/models'; +import { RichTreeView } from '@mui/x-tree-view/RichTreeView'; + +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' }, + ], + }, + { + id: 'charts', + label: 'Charts', + children: [ + { id: 'charts-community', label: '@mui/x-charts' }, + { id: 'charts-pro', label: '@mui/charts-pro' }, + ], + }, + { + id: 'tree-view', + label: 'Tree View', + children: [ + { id: 'tree-view-community', label: '@mui/x-tree-view' }, + { id: 'tree-view-pro', label: '@mui/x-tree-view-pro' }, + ], + }, +]; + +export default function BasicRichTreeView() { + return ( + + + + ); +} diff --git a/docs/data/tree-view/quickstart/BasicRichTreeView.tsx.preview b/docs/data/tree-view/quickstart/BasicRichTreeView.tsx.preview new file mode 100644 index 0000000000000..19ab6390267f1 --- /dev/null +++ b/docs/data/tree-view/quickstart/BasicRichTreeView.tsx.preview @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/data/tree-view/quickstart/BasicSimpleTreeView.js b/docs/data/tree-view/quickstart/BasicSimpleTreeView.js new file mode 100644 index 0000000000000..881c0250ed3c6 --- /dev/null +++ b/docs/data/tree-view/quickstart/BasicSimpleTreeView.js @@ -0,0 +1,30 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; +import { TreeItem } from '@mui/x-tree-view/TreeItem'; + +export default function BasicSimpleTreeView() { + return ( + + + + + + + + + + + + + + + + + + + + + + ); +} diff --git a/docs/data/tree-view/quickstart/BasicSimpleTreeView.tsx b/docs/data/tree-view/quickstart/BasicSimpleTreeView.tsx new file mode 100644 index 0000000000000..881c0250ed3c6 --- /dev/null +++ b/docs/data/tree-view/quickstart/BasicSimpleTreeView.tsx @@ -0,0 +1,30 @@ +import * as React from 'react'; +import Box from '@mui/material/Box'; +import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; +import { TreeItem } from '@mui/x-tree-view/TreeItem'; + +export default function BasicSimpleTreeView() { + return ( + + + + + + + + + + + + + + + + + + + + + + ); +} diff --git a/docs/data/tree-view/getting-started/FirstComponent.js b/docs/data/tree-view/quickstart/FirstComponent.js similarity index 100% rename from docs/data/tree-view/getting-started/FirstComponent.js rename to docs/data/tree-view/quickstart/FirstComponent.js diff --git a/docs/data/tree-view/getting-started/FirstComponent.tsx b/docs/data/tree-view/quickstart/FirstComponent.tsx similarity index 100% rename from docs/data/tree-view/getting-started/FirstComponent.tsx rename to docs/data/tree-view/quickstart/FirstComponent.tsx diff --git a/docs/data/tree-view/quickstart/quickstart.md b/docs/data/tree-view/quickstart/quickstart.md new file mode 100644 index 0000000000000..eb2a6660a6f76 --- /dev/null +++ b/docs/data/tree-view/quickstart/quickstart.md @@ -0,0 +1,122 @@ +--- +productId: x-tree-view +title: Tree View - Quickstart +components: SimpleTreeView, RichTreeView, TreeItem, TreeView +packageName: '@mui/x-tree-view' +githubLabel: 'component: tree view' +waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/ +--- + +# Tree View - Quickstart + +

Install the MUI X Tree View package and start building.

+ +## Installation + +Install the Tree View package that best suits your needs—Community or Pro: + + + +{{"component": "modules/components/TreeViewInstallationInstructions.js"}} + +### Peer dependencies + +#### Material UI + +The Tree View packages have a peer dependency on `@mui/material`. +If you're not already using it, install it now: + + + +```bash npm +npm install @mui/material @emotion/react @emotion/styled +``` + +```bash pnpm +pnpm add @mui/material @emotion/react @emotion/styled +``` + +```bash yarn +yarn add @mui/material @emotion/react @emotion/styled +``` + + + +#### React + + + +[`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) are also peer dependencies: + +```json +"peerDependencies": { + "react": "^17.0.0 || ^18.0.0 || ^19.0.0", + "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0" +}, +``` + +## Rendering a Tree View + +The package exposes two different versions of this component: `` and ``. +The [Simple version](#simple-tree-view) is recommended for hardcoded items, while the [Rich version](#rich-tree-view) is preferred for dynamically rendered items, larger trees, and more complex use cases that require features like editing and virtualization. + +:::info +Currently, the Simple and Rich Tree View components share many of the same features. +As this package continues to mature, more advanced features and functionality will be prioritized for the Rich Tree View. +::: + +### Simple Tree View + +```jsx +import { SimpleTreeView } from '@mui/x-tree-view/SimpleTreeView'; +``` + +The simple version of the Tree View component receives its items as JSX children. +This is the recommended version for hardcoded items. + +{{"demo": "BasicSimpleTreeView.js"}} + +### Rich Tree View + +```jsx +import { RichTreeView } from '@mui/x-tree-view/RichTreeView'; +``` + +The rich version of the Tree View component receives its items dynamically from an external data source. +This is the recommended version for larger trees, as well as those that require more advanced features like editing and virtualization. + +{{"demo": "BasicRichTreeView.js"}} + +### Accessibility + +The MUI X Tree View follows the [WAI-ARIA authoring practices for a tree view](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/). +The component includes many built-in [accessibility features](/x/react-tree-view/accessibility/), but it's the developer's responsibilty to provide the component with a descriptive `aria-labelledby`or `aria-label` tag—otherwise, screen readers will announce it as "tree," making it difficult for the end user to understand the purpose of the tree items. + +## TypeScript + +### Theme augmentation + +To benefit from [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users must import the following types. +These types use module augmentation to extend the default theme structure. + +```tsx +// Pro users: add `-pro` suffix to package name +import type {} from '@mui/x-tree-view/themeAugmentation'; + +const theme = createTheme({ + components: { + MuiRichTreeView: { + styleOverrides: { + root: { + backgroundColor: 'red', + }, + }, + }, + }, +}); +``` + +## Using this documentation + +Although the Simple and Rich Tree View share many of the same features, each version's implementation of those features differs enough that they warrant their own separate docs in most cases. +Other features, such as accessibility, work the same in both versions and are documented in the main features section of the navigation bar. diff --git a/docs/pages/x/api/tree-view/rich-tree-view.json b/docs/pages/x/api/tree-view/rich-tree-view.json index a97c841a6e9af..768cf203c6859 100644 --- a/docs/pages/x/api/tree-view/rich-tree-view.json +++ b/docs/pages/x/api/tree-view/rich-tree-view.json @@ -166,6 +166,6 @@ "forwardsRefTo": "HTMLUListElement", "filename": "/packages/x-tree-view/src/RichTreeView/RichTreeView.tsx", "inheritance": null, - "demos": "", + "demos": "", "cssComponent": false } diff --git a/docs/pages/x/api/tree-view/simple-tree-view.json b/docs/pages/x/api/tree-view/simple-tree-view.json index da75d42ee0b8f..42ad9204d600c 100644 --- a/docs/pages/x/api/tree-view/simple-tree-view.json +++ b/docs/pages/x/api/tree-view/simple-tree-view.json @@ -121,6 +121,6 @@ "forwardsRefTo": "HTMLUListElement", "filename": "/packages/x-tree-view/src/SimpleTreeView/SimpleTreeView.tsx", "inheritance": null, - "demos": "", + "demos": "", "cssComponent": false } diff --git a/docs/pages/x/api/tree-view/tree-item.json b/docs/pages/x/api/tree-view/tree-item.json index f1383007b5fe1..434b948c7af17 100644 --- a/docs/pages/x/api/tree-view/tree-item.json +++ b/docs/pages/x/api/tree-view/tree-item.json @@ -124,6 +124,6 @@ "forwardsRefTo": "HTMLLIElement", "filename": "/packages/x-tree-view/src/TreeItem/TreeItem.tsx", "inheritance": null, - "demos": "", + "demos": "", "cssComponent": false } diff --git a/docs/pages/x/react-charts/getting-started.js b/docs/pages/x/react-charts/quickstart.js similarity index 66% rename from docs/pages/x/react-charts/getting-started.js rename to docs/pages/x/react-charts/quickstart.js index fcb53b26968b1..d4a6aaa15a74b 100644 --- a/docs/pages/x/react-charts/getting-started.js +++ b/docs/pages/x/react-charts/quickstart.js @@ -1,6 +1,6 @@ import * as React from 'react'; import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; -import * as pageProps from 'docsx/data/charts/getting-started/getting-started.md?muiMarkdown'; +import * as pageProps from 'docsx/data/charts/quickstart/quickstart.md?muiMarkdown'; export default function Page() { return ; diff --git a/docs/pages/x/react-data-grid/demo.js b/docs/pages/x/react-data-grid/features.js similarity index 70% rename from docs/pages/x/react-data-grid/demo.js rename to docs/pages/x/react-data-grid/features.js index 0e8f0e21416c6..8054866320172 100644 --- a/docs/pages/x/react-data-grid/demo.js +++ b/docs/pages/x/react-data-grid/features.js @@ -1,6 +1,6 @@ import * as React from 'react'; import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; -import * as pageProps from 'docsx/data/data-grid/demo/demo.md?muiMarkdown'; +import * as pageProps from 'docsx/data/data-grid/features/features.md?muiMarkdown'; export default function Page() { return ; diff --git a/docs/pages/x/react-data-grid/getting-started.js b/docs/pages/x/react-data-grid/quickstart.js similarity index 65% rename from docs/pages/x/react-data-grid/getting-started.js rename to docs/pages/x/react-data-grid/quickstart.js index 005cd237802b2..82b409fc3d4a2 100644 --- a/docs/pages/x/react-data-grid/getting-started.js +++ b/docs/pages/x/react-data-grid/quickstart.js @@ -1,6 +1,6 @@ import * as React from 'react'; import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; -import * as pageProps from 'docsx/data/data-grid/getting-started/getting-started.md?muiMarkdown'; +import * as pageProps from 'docsx/data/data-grid/quickstart/quickstart.md?muiMarkdown'; export default function Page() { return ; diff --git a/docs/pages/x/react-date-pickers/getting-started.js b/docs/pages/x/react-date-pickers/quickstart.js similarity index 65% rename from docs/pages/x/react-date-pickers/getting-started.js rename to docs/pages/x/react-date-pickers/quickstart.js index a158c4ae22ba2..0bd6a4c47f663 100644 --- a/docs/pages/x/react-date-pickers/getting-started.js +++ b/docs/pages/x/react-date-pickers/quickstart.js @@ -1,6 +1,6 @@ import * as React from 'react'; import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; -import * as pageProps from 'docsx/data/date-pickers/getting-started/getting-started.md?muiMarkdown'; +import * as pageProps from 'docsx/data/date-pickers/quickstart/quickstart.md?muiMarkdown'; export default function Page() { return ; diff --git a/docs/pages/x/react-tree-view/getting-started.js b/docs/pages/x/react-tree-view/getting-started.js deleted file mode 100644 index f0279289f29b2..0000000000000 --- a/docs/pages/x/react-tree-view/getting-started.js +++ /dev/null @@ -1,7 +0,0 @@ -import * as React from 'react'; -import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; -import * as pageProps from 'docsx/data/tree-view/getting-started/getting-started.md?muiMarkdown'; - -export default function Page() { - return ; -} diff --git a/docs/pages/x/react-date-pickers/faq.js b/docs/pages/x/react-tree-view/quickstart.js similarity index 67% rename from docs/pages/x/react-date-pickers/faq.js rename to docs/pages/x/react-tree-view/quickstart.js index d99c53ff3582d..c212c50d2b434 100644 --- a/docs/pages/x/react-date-pickers/faq.js +++ b/docs/pages/x/react-tree-view/quickstart.js @@ -1,6 +1,6 @@ import * as React from 'react'; import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; -import * as pageProps from 'docsx/data/date-pickers/faq/faq.md?muiMarkdown'; +import * as pageProps from 'docsx/data/tree-view/quickstart/quickstart.md?muiMarkdown'; export default function Page() { return ; diff --git a/docs/public/_redirects b/docs/public/_redirects index d025efe45dd55..bbefb47723e45 100644 --- a/docs/public/_redirects +++ b/docs/public/_redirects @@ -61,5 +61,11 @@ # 2024 /x/react-charts/heat-map/ /x/react-charts/heatmap/ 301 /x/react-charts/tree-map/ /x/react-charts/treemap/ 301 +# 2025 +/x/react-charts/getting-started/ /x/react-charts/quickstart/ 301 +/x/react-data-grid/getting-started/ /x/react-data-grid/quickstart/ 301 +/x/react-date-pickers/getting-started/ /x/react-date-pickers/quickstart/ 301 +/x/react-tree-view/getting-started/ /x/react-tree-view/quickstart/ 301 +/x/react-data-grid/demo/ /x/react-data-grid/features/ 301 # Proxies diff --git a/docsTech/README.md b/docsTech/README.md index 0bd0f70fede6e..623f821d468c7 100644 --- a/docsTech/README.md +++ b/docsTech/README.md @@ -2,8 +2,8 @@

MUI X DataGrid overview

-Welcome in the documentation for contributors. If you want to use DataGrid components for your project, the [documentation for developers](https://mui.com/x/react-data-grid/getting-started/) is more appropriate. -Here we will discuss how the code is structured, to simplify codebase navigation, and onboard new contributors. +Welcome to the documentation for contributors. If you want to use Data Grid components for your project, the [documentation for developers](https://mui.com/x/react-data-grid/) is more appropriate. +Here we discuss how the code is structured to simplify codebase navigation and onboard new contributors. ## Where is the code? diff --git a/packages/x-data-grid-premium/src/DataGridPremium/DataGridPremium.tsx b/packages/x-data-grid-premium/src/DataGridPremium/DataGridPremium.tsx index c470e57eebff7..43eafe3c9737e 100644 --- a/packages/x-data-grid-premium/src/DataGridPremium/DataGridPremium.tsx +++ b/packages/x-data-grid-premium/src/DataGridPremium/DataGridPremium.tsx @@ -1128,8 +1128,8 @@ interface DataGridPremiumComponent { } /** - * Demos: - * - [DataGridPremium](https://mui.com/x/react-data-grid/demo/) + * Features: + * - [DataGridPremium](https://mui.com/x/react-data-grid/features/) * * API: * - [DataGridPremium API](https://mui.com/x/api/data-grid/data-grid-premium/) diff --git a/packages/x-data-grid-pro/src/DataGridPro/DataGridPro.tsx b/packages/x-data-grid-pro/src/DataGridPro/DataGridPro.tsx index b5e5db188f596..e294605d3e477 100644 --- a/packages/x-data-grid-pro/src/DataGridPro/DataGridPro.tsx +++ b/packages/x-data-grid-pro/src/DataGridPro/DataGridPro.tsx @@ -59,8 +59,8 @@ interface DataGridProComponent { } /** - * Demos: - * - [DataGridPro](https://mui.com/x/react-data-grid/demo/) + * Features: + * - [DataGridPro](https://mui.com/x/react-data-grid/features/) * * API: * - [DataGridPro API](https://mui.com/x/api/data-grid/data-grid-pro/) diff --git a/packages/x-data-grid/src/DataGrid/DataGrid.tsx b/packages/x-data-grid/src/DataGrid/DataGrid.tsx index f1c596141ed89..65564724e454c 100644 --- a/packages/x-data-grid/src/DataGrid/DataGrid.tsx +++ b/packages/x-data-grid/src/DataGrid/DataGrid.tsx @@ -52,8 +52,8 @@ interface DataGridComponent { } /** - * Demos: - * - [DataGrid](https://mui.com/x/react-data-grid/demo/) + * Features: + * - [DataGrid](https://mui.com/x/react-data-grid/features/) * * API: * - [DataGrid API](https://mui.com/x/api/data-grid/data-grid/) diff --git a/test/e2e-website/data-grid.spec.ts b/test/e2e-website/data-grid.spec.ts index 8741370add69e..26d75a3118b43 100644 --- a/test/e2e-website/data-grid.spec.ts +++ b/test/e2e-website/data-grid.spec.ts @@ -6,7 +6,7 @@ const test = base.extend({}); test.describe('DataGrid docs', () => { test('should have correct link with hash in the TOC', async ({ page }) => { - await page.goto(`/x/react-data-grid/getting-started/`); + await page.goto(`/x/react-data-grid/quickstart/`); const anchors = page.locator('[aria-label="Page table of contents"] ul a'); @@ -15,7 +15,7 @@ test.describe('DataGrid docs', () => { await expect(firstAnchor).toHaveAttribute( 'href', - `/x/react-data-grid/getting-started/#${kebabCase(textContent || '')}`, + `/x/react-data-grid/quickstart/#${kebabCase(textContent || '')}`, ); }); @@ -90,7 +90,7 @@ test.describe('DataGrid docs', () => { // } // }; // test('should have correct link when searching component', async ({ page }) => { - // await page.goto(`/x/react-data-grid/getting-started/`); + // await page.goto(`/x/react-data-grid/quickstart/`); // await retryToggleSearch(page); @@ -106,7 +106,7 @@ test.describe('DataGrid docs', () => { // }); // test('should have correct link when searching API', async ({ page }) => { - // await page.goto(`/x/react-data-grid/getting-started/`); + // await page.goto(`/x/react-data-grid/quickstart/`); // await retryToggleSearch(page); @@ -122,7 +122,7 @@ test.describe('DataGrid docs', () => { // }); // test('should have correct link when searching pro API', async ({ page }) => { - // await page.goto(`/x/react-data-grid/getting-started/`); + // await page.goto(`/x/react-data-grid/quickstart/`); // await retryToggleSearch(page);