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.

Sign up for GitHub

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

Jump to bottom

[docs] Edit the Pickers Getting started doc #14555

Merged
merged 5 commits into from
Sep 18, 2024
Merged

[docs] Edit the Pickers Getting started doc #14555

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
495d748
first pass
samuelsycamore Sep 9, 2024
add9260
prettier
samuelsycamore Sep 9, 2024
326cd04
Update docs/data/date-pickers/getting-started/getting-started.md
samuelsycamore Sep 10, 2024
2f04717
Update docs/data/date-pickers/getting-started/getting-started.md
michelengelen Sep 17, 2024
3b258d6
Apply suggestions from code review
samuelsycamore Sep 18, 2024
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
98 changes: 37 additions & 61 deletions docs/data/date-pickers/getting-started/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,38 @@
---
productId: x-date-pickers
title: Date and Time Picker - Getting started
title: Date and Time Pickers - Getting started
Copy link
Member Author

@samuelsycamore samuelsycamore Sep 9, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

noticed this throughout these docs - Pickers should always be plural in this context

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
# Date and Time Pickers - Getting started

<p class="description">Get started with the Date and Time Pickers. Install the package, configure your application and start using the components.</p>
<p class="description">Install the Date and Time Pickers and set up your date library to start building.</p>
samuelsycamore marked this conversation as resolved.
Show resolved Hide resolved

## Installation

Using your favorite package manager, install:
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/).
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

feels much better to have this info right here rather than needing to visit the base concepts page


- `@mui/x-date-pickers` for the free community version or `@mui/x-date-pickers-pro` for the commercial version.
- The date library to manipulate the date.
Choose your packages and manager through the toggles below, then run the commands as provided to install:

<!-- #default-branch-switch -->

{{"component": "modules/components/PickersInstallationInstructions.js"}}

:::info
If you need more information about the date library supported by the Date and Time Pickers,
take a look at the [dedicated section](/x/react-date-pickers/base-concepts/#date-library)
:::success
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

another one that feels more useful here than in base concepts

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@LukasTy related to our topic from yesterday. With all the problems dayJs has regarding timezones and its relatively unmaintained state are we sure we want to recommend that?

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.
:::

The Date and Time Pickers package has a peer dependency on `@mui/material`.
If you are not already using it in your project, you can install it with:
### Peer dependencies

#### Material UI

Check failure on line 32 in docs/data/date-pickers/getting-started/getting-started.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Material UI' instead of 'Material UI')

Raw Output:
{"message": "[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Material UI' instead of 'Material UI')", "location": {"path": "docs/data/date-pickers/getting-started/getting-started.md", "range": {"start": {"line": 32, "column": 6}}}, "severity": "ERROR"}
michelengelen marked this conversation as resolved.
Show resolved Hide resolved

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:

<codeblock storageKey="package-manager">

Expand All @@ -46,9 +50,11 @@

</codeblock>

#### React

<!-- #react-peer-version -->

Please note that [react](https://www.npmjs.com/package/react) and [react-dom](https://www.npmjs.com/package/react-dom) are peer dependencies too:
[`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) are also peer dependencies:

```json
"peerDependencies": {
Expand All @@ -57,70 +63,40 @@
},
```

### Style engine
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this info really necessary? Looks like copypasta from the Material UI docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it is actually a copypasta, given that most users probably stick to default—Emotion, there is little need for this section here. 👍


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:

<codeblock storageKey="package-manager">
## Date library adapter setup

```bash npm
npm install @mui/styled-engine-sc styled-components
```
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.

```bash pnpm
pnpm add @mui/styled-engine-sc styled-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:
michelengelen marked this conversation as resolved.
Show resolved Hide resolved

```bash yarn
yarn add @mui/styled-engine-sc styled-components
```tsx
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { AdapterDayjs } from '@mui/x-date-pickers-pro/AdapterDayjs';
```

</codeblock>

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.

## Setup your date library adapter
### LocalizationProvider

Before trying to render any component, you have to make sure that there is a `LocalizationProvider` upper in the React tree.
This component receives your chosen [date library's adapter](https://mui.com/x/react-date-pickers/#date-library) (the doc uses `AdapterDayjs` which is based on [dayjs](https://day.js.org/)) and makes it accessible to all the Date and Time Pickers component using React context.
The `LocalizationProvider` component is exported by both `@mui/x-date-pickers` and `@mui/x-date-pickers-pro`:

Each demonstration in the documentation has its own `LocalizationProvider` wrapper.
This is **not** a pattern to reproduce.
The reason is to keep examples atomic and functional, especially when running in a CodeSandbox.
```tsx
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { LocalizationProvider } from '@mui/x-date-pickers-pro/LocalizationProvider';
```

The general recommendation is to declare the `LocalizationProvider` once, wrapping your entire application.
Then, you don't need to repeat the boilerplate code for every Date and Time Picker in your application.
:::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"}}

:::success

- All the adapters are exported by both `@mui/x-date-pickers` and `@mui/x-date-pickers-pro`:

```tsx
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { AdapterDayjs } from '@mui/x-date-pickers-pro/AdapterDayjs';
```

- `LocalizationProvider` 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';
```

:::

:::info
If you need to use the Date and Time Pickers with a custom locale, have a look at the [Localized dates](/x/react-date-pickers/adapters-locale/) page.
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 make sure that everything is set up correctly, try rendering a simple `DatePicker` component:
To confirm that everything is set up correctly, try rendering a basic Date Picker component:

{{"demo": "FirstComponent.js"}}

## What's next?
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this feels unnecessary when "what's next" is already baked into the design of the docs at the bottom of the page.


Continue to the [next page](/x/react-date-pickers/base-concepts/) and discover the components available and how to use them.
1 change: 0 additions & 1 deletion docs/src/modules/components/PickersInstallationInstructions.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ const packages = {

const peerDependency = {
label: 'Date library',
installationComment: '// Install date library (if not already installed)',
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this really necessary? feels like it just clutters the space

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be clear enough without it. 👍
Besides, comments are not rendered properly (no different styling). 🙈 🤷

packages: ['dayjs', 'date-fns', 'luxon', 'moment'],
};

Expand Down
Loading