Skip to content

Commit 90c8386

Browse files
fzaninottofzaninotto
authored
Merge pull request #9631 from marmelab/update-doc-for-MUI-X-date-time-pickers
[Documentation] Update docs for MUI X date/time pickers
2 parents 6ffb08e + 85173af commit 90c8386

6 files changed

+234
-1
lines changed

‎docs/DateInput.md

+77
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ Ideal for editing dates, `<DateInput>` renders an HTML `<input type="date">` ele
1616

1717
The appearance of `<DateInput>` depends on the browser, and falls back to a text input on Safari. The date formatting in this input depends on the user's locale.
1818

19+
React-admin also proposes a [DateInput styled with Material UI](#material-ui) documented at the end of this page.
20+
1921
## Usage
2022

2123
```jsx
@@ -53,3 +55,78 @@ If you need to render a UI despite the browser locale, MUI also proposes a [Date
5355
Your browser does not support the video tag.
5456
</video>
5557

58+
## Material UI
59+
60+
[React-admin Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> proposes an alternative `<DateInput>` styled with Material UI.
61+
62+
![DateInput with Material UI](./img/DateInput-MUI.png)
63+
64+
This input also allows to specify the date format and the locale used. It is based on the [MUI X Date/Time pickers](https://mui.com/x/react-date-pickers/getting-started/).
65+
66+
### Usage
67+
68+
```tsx
69+
import { DateInput } from '@react-admin/ra-form-layout';
70+
import { Edit, SimpleForm } from 'react-admin';
71+
72+
export const EventEdit = () => (
73+
<Edit>
74+
<SimpleForm>
75+
<DateInput source="event_date" />
76+
</SimpleForm>
77+
</Edit>
78+
);
79+
```
80+
81+
`<DateInput>` will accept either a `Date` object or any string that can be parsed into a `Date` as value. It will return a `Date` object, or `null` if the date is invalid.
82+
83+
**Tip:** You can use the `parse` prop to change the format of the returned value. See [Parsing the date/time as an ISO string](#parsing-the-datetime-as-an-iso-string) for an example.
84+
85+
### Props
86+
87+
| Prop | Required | Type | Default | Description |
88+
| ------------ | -------- | ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
89+
| `fullWidth` | - | boolean | `false` | If `true`, the input will expand to fill the form width |
90+
| `helperText` | - | string | - | Text to be displayed under the input |
91+
| `mask` | - | string | - | Alias for the MUI [`format`](https://mui.com/x/api/date-pickers/date-picker/#DatePicker-prop-format) prop. Format of the date/time when rendered in the input. Defaults to localized format. |
92+
| `parse` | - | Function | `value => value === '' ? null : value` | Callback taking the input value, and returning the value you want stored in the form state. |
93+
| `validate` | - | Function or Array | - | Validation rules for the input. See the [Validation Documentation](https://marmelab.com/react-admin/Validation.html#per-input-validation-built-in-field-validators) for details. |
94+
95+
Except for the `format` prop (renamed `mask`), `<DateInput>` accepts the same props as the [MUI X Date/Time pickers](https://mui.com/x/api/date-pickers/). They also accept the common input props.
96+
97+
### Providing your own `LocalizationProvider`
98+
99+
MUI X Pickers need to be wrapped in a [LocalizationProvider](https://mui.com/components/pickers/#localization) to work properly. `<DateInput>` already includes a default `<LocalizationProvider>` using the `date-fns` adapter and the `enUS` locale.
100+
101+
You can change the locale and the date format globally by wrapping the `<Admin>` with your own `<LocalizationProvider>`.
102+
103+
Here is how to set up the pickers to use the `fr` locale:
104+
105+
```tsx
106+
import { Admin, Resource } from 'react-admin';
107+
import { LocalizationProvider } from '@mui/x-date-pickers';
108+
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
109+
import { fr } from 'date-fns/locale';
110+
import { EventEdit } from './events';
111+
112+
export const App = () => (
113+
<LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={fr}>
114+
<Admin>
115+
<Resource name="events" edit={EventEdit} />
116+
</Admin>
117+
</LocalizationProvider>
118+
);
119+
```
120+
121+
**Note:** React Admin only supports the `date-fns` adapter for now.
122+
123+
### Parsing the date/time as an ISO string
124+
125+
By default, `<DateInput>` stores the date/time as a `Date` object in the form state. If you wish to store the date/time as an ISO string instead (or any other format), you can use the `parse` prop.
126+
127+
```tsx
128+
<DateInput
129+
source="published"
130+
parse={(date: Date) => (date ? date.toISOString() : null)}
131+
/>
132+
```

‎docs/DateTimeInput.md

+79-1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ An input for editing dates with time. `<DateTimeInput>` renders an `<input type=
1616

1717
The appearance depends on the browser, and falls back to a text input on safari. The date formatting in this input depends on the user's locale.
1818

19+
React-admin also proposes a [DateTimeInput styled with Material UI](#material-ui) documented at the end of this page.
20+
1921
## Usage
2022

2123
```jsx
@@ -38,4 +40,80 @@ After modification by the user, the value is stored as a `Date` object, using th
3840

3941
Internally, `<DateTimeInput>` renders an [`<input type="datetime-local">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local).
4042

41-
If you need to implement your own `format` and `parse` functions, make sure the **format** function actually formats the input into [a valid local date and time string](https://developer.mozilla.org/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings).
43+
If you need to implement your own `format` and `parse` functions, make sure the **format** function actually formats the input into [a valid local date and time string](https://developer.mozilla.org/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings).
44+
45+
## Material UI
46+
47+
[React-admin Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> proposes an alternative `<DateTimeInput>` styled with Material UI.
48+
49+
![DateTimeInput with Material UI](./img/DateTimeInput-MUI.png)
50+
51+
This input also allows to specify the date format and the locale used. It is based on the [MUI X Date/Time pickers](https://mui.com/x/react-date-pickers/getting-started/).
52+
53+
### Usage
54+
55+
```tsx
56+
import { DateTimeInput } from '@react-admin/ra-form-layout';
57+
import { Edit, SimpleForm } from 'react-admin';
58+
59+
export const EventEdit = () => (
60+
<Edit>
61+
<SimpleForm>
62+
<DateTimeInput source="event_date" />
63+
</SimpleForm>
64+
</Edit>
65+
);
66+
```
67+
68+
`<DateTimeInput>` will accept either a `Date` object or any string that can be parsed into a `Date` as value. It will return a `Date` object, or `null` if the date is invalid.
69+
70+
**Tip:** You can use the `parse` prop to change the format of the returned value. See [Parsing the date/time as an ISO string](#parsing-the-datetime-as-an-iso-string) for an example.
71+
72+
### Props
73+
74+
| Prop | Required | Type | Default | Description |
75+
| ------------ | -------- | ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76+
| `fullWidth` | - | boolean | `false` | If `true`, the input will expand to fill the form width |
77+
| `helperText` | - | string | - | Text to be displayed under the input |
78+
| `mask` | - | string | - | Alias for the MUI [`format`](https://mui.com/x/api/date-pickers/date-picker/#DatePicker-prop-format) prop. Format of the date/time when rendered in the input. Defaults to localized format. |
79+
| `parse` | - | Function | `value => value === '' ? null : value` | Callback taking the input value, and returning the value you want stored in the form state. |
80+
| `validate` | - | Function or Array | - | Validation rules for the input. See the [Validation Documentation](https://marmelab.com/react-admin/Validation.html#per-input-validation-built-in-field-validators) for details. |
81+
82+
Except for the `format` prop (renamed `mask`), `<DateTimeInput> accepts the same props as the [MUI X Date/Time pickers](https://mui.com/x/api/date-pickers/). They also accept the common input props.
83+
84+
### Providing your own `LocalizationProvider`
85+
86+
MUI X Pickers need to be wrapped in a [LocalizationProvider](https://mui.com/components/pickers/#localization) to work properly. `<DateTimeInput>` already includes a default `<LocalizationProvider>` using the `date-fns` adapter and the `enUS` locale.
87+
88+
You can change the locale and the date format globally by wrapping the `<Admin>` with your own `<LocalizationProvider>`.
89+
90+
Here is how to set up the pickers to use the `fr` locale:
91+
92+
```tsx
93+
import { Admin, Resource } from 'react-admin';
94+
import { LocalizationProvider } from '@mui/x-date-pickers';
95+
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
96+
import { fr } from 'date-fns/locale';
97+
import { EventEdit } from './events';
98+
99+
export const App = () => (
100+
<LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={fr}>
101+
<Admin>
102+
<Resource name="events" edit={EventEdit} />
103+
</Admin>
104+
</LocalizationProvider>
105+
);
106+
```
107+
108+
**Note:** React Admin only supports the `date-fns` adapter for now.
109+
110+
### Parsing the date/time as an ISO string
111+
112+
By default, `<DateTimeInput>` stores the date/time as a `Date` object in the form state. If you wish to store the date/time as an ISO string instead (or any other format), you can use the `parse` prop.
113+
114+
```tsx
115+
<DateTimeInput
116+
source="published"
117+
parse={(date: Date) => (date ? date.toISOString() : null)}
118+
/>
119+
```

‎docs/TimeInput.md

+78
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ An input for editing time. `<TimeInput>` renders a standard browser [Time Picker
3737
This component works with Date objects to handle the timezone using the browser locale.
3838
You can still pass string values as long as those can be converted to a JavaScript Date object.
3939

40+
React-admin also proposes a [TimeInput styled with Material UI](#material-ui) documented at the end of this page.
41+
4042
## Usage
4143

4244
```jsx
@@ -51,3 +53,79 @@ import { TimeInput } from 'react-admin';
5153

5254
`<TimeInput>` accepts the [common input props](./Inputs.md#common-input-props).
5355

56+
57+
## Material UI
58+
59+
[React-admin Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> proposes an alternative `<TimeInput>` styled with Material UI.
60+
61+
![TimeInput with Material UI](./img/TimeInput-MUI.png)
62+
63+
It allows for more customization of the UI than the default browser pickers. It also make it easier to work with specific locale and date formats.
64+
65+
### Usage
66+
67+
```tsx
68+
import { TimeInput } from '@react-admin/ra-form-layout';
69+
import { Edit, SimpleForm } from 'react-admin';
70+
71+
export const EventEdit = () => (
72+
<Edit>
73+
<SimpleForm>
74+
<TimeInput source="event_date" />
75+
</SimpleForm>
76+
</Edit>
77+
);
78+
```
79+
80+
`<TimeInput>` will accept either a `Date` object or any string that can be parsed into a `Date` as value. It will return a `Date` object, or `null` if the date is invalid.
81+
82+
**Tip:** You can use the `parse` prop to change the format of the returned value. See [Parsing the date/time as an ISO string](#parsing-the-datetime-as-an-iso-string) for an example.
83+
84+
### Props
85+
86+
| Prop | Required | Type | Default | Description |
87+
| ------------ | -------- | ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
88+
| `fullWidth` | - | boolean | `false` | If `true`, the input will expand to fill the form width |
89+
| `helperText` | - | string | - | Text to be displayed under the input |
90+
| `mask` | - | string | - | Alias for the MUI [`format`](https://mui.com/x/api/date-pickers/date-picker/#DatePicker-prop-format) prop. Format of the date/time when rendered in the input. Defaults to localized format. |
91+
| `parse` | - | Function | `value => value === '' ? null : value` | Callback taking the input value, and returning the value you want stored in the form state. |
92+
| `validate` | - | Function or Array | - | Validation rules for the input. See the [Validation Documentation](https://marmelab.com/react-admin/Validation.html#per-input-validation-built-in-field-validators) for details. |
93+
94+
Except for the `format` prop (renamed `mask`), `<TimeInput> accepts the same props as the [MUI X Date/Time pickers](https://mui.com/x/api/date-pickers/). They also accept the common input props.
95+
96+
### Providing your own `LocalizationProvider`
97+
98+
MUI X Pickers need to be wrapped in a [LocalizationProvider](https://mui.com/components/pickers/#localization) to work properly. `<TimeInput>` already includes a default `<LocalizationProvider>` using the `date-fns` adapter and the `enUS` locale.
99+
100+
You can change the locale and the date format globally by wrapping the `<Admin>` with your own `<LocalizationProvider>`.
101+
102+
Here is how to set up the pickers to use the `fr` locale:
103+
104+
```tsx
105+
import { Admin, Resource } from 'react-admin';
106+
import { LocalizationProvider } from '@mui/x-date-pickers';
107+
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
108+
import { fr } from 'date-fns/locale';
109+
import { EventEdit } from './events';
110+
111+
export const App = () => (
112+
<LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={fr}>
113+
<Admin>
114+
<Resource name="events" edit={EventEdit} />
115+
</Admin>
116+
</LocalizationProvider>
117+
);
118+
```
119+
120+
**Note:** React Admin only supports the `date-fns` adapter for now.
121+
122+
### Parsing the date/time as an ISO string
123+
124+
By default, `<TimeInput>` stores the date/time as a `Date` object in the form state. If you wish to store the date/time as an ISO string instead (or any other format), you can use the `parse` prop.
125+
126+
```tsx
127+
<TimeInput
128+
source="published"
129+
parse={(date: Date) => (date ? date.toISOString() : null)}
130+
/>
131+
```

‎docs/img/DateInput-MUI.png

28.3 KB
Loading

‎docs/img/DateTimeInput-MUI.png

39.4 KB
Loading

‎docs/img/TimeInput-MUI.png

22.9 KB
Loading

0 commit comments

Comments
 (0)