Date and time value
Usage
This is a utility component for rendering and formatting data, so there are no specific UX guidelines.
Code
<DateValue date={new Date('2025-01-15')} />
Import statement
import { DateValue } from '@jutro/components';
Component contract
Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.
Properties
className- Type
stringDescriptionCSS class name for this component.
date- Type
DateDescriptionDate value override to be used instead of the one provided with props.
displayFormat- Type
'vshort' | 'short' | 'long' | 'abbreviated' | 'full'DescriptionThe date format used to display the date.
id- Type
stringDescriptionUnique identifier for the component.
inputFormat- Type
stringDescriptionFormat of the date displayed when the value is edited. Used to retrieve tokens that will be displayed.
path- Type
stringDescriptionSpecifies the path to the value used to generate the output.
placeholder- TypeDescription
The string to display if 'date' is undefined/null.
prefix- TypeDescription
Optional prefix message to be attached before the value.
skipTimeZone- Type
booleanDescriptionIf set to
true, the date won't be converted to defaultTimezone. Use if the date is already converted to the desired time zone. suffix- TypeDescription
Optional suffix message to be attached after the value.
tag- Type
stringDescriptionThe HTML tag to use when rendering the outermost element of this component.
Default value'div' value- Description
A value to convert into a Date. See later in this document for explanation of accepted formats.
DateObjectValueShape
DateObjectValueShape type is an object that represents a date. It's has the following properties:
yearrequired- Type
numberDescriptionYears counting from 0 CE.
day- Type
numberDescriptionThe day of the month. Max value depends on the month and whether it is a leap year.
hour- Type
numberDescriptionHour of the day, following the 24 hour clock. Must be between 0 and 23 inclusive.
minute- Type
numberDescriptionMinute of the hour. Must be between 0 and 59 inclusive.
month- Type
numberDescriptionMonth of the year counted from 0. For example, 0 is January, 1 is February, and so on.
Valid formats for value property
The value property accepts the following formats:
| Type | Expected format |
|---|---|
string | yyyy-dd-MM |
number | Epoch Unix Timestamp given in milliseconds |
Date | javascript Date object |
DateObjectValueShape | A DateObjectValueShape object |
Imperative API
jutro-components offers the formatDate function for use with the imperative formatting API.
import { formatDate } from '@jutro/components';
This imports a function formatDate(intl, props, date) with the following arguments and return type:
Return value
- Type
stringDescriptionFormatted date string.
date- Description
Date value override to be used instead of the one provided with props.
intl- Type
react.intl.IntlDescriptionAn instance of the imperative formatting API access object.
props- Type
DateValue.propTypesDescriptionValid properties for a
DateValueobject.
Hooks
No hooks are available for date value.
Translation keys
There are no translations for date value.
For information on how to manage translations, see our section about Internationalization.
Escape hatches
For more information, see our documentation about escape hatches.
Examples
Check out the Usage section for details about how to design a date value properly, and the different configuration options we provide.
Basic date value example
You can use the DateValue component to render a JavaScript Date.
<DateValue date={new Date('2025-01-15')} />
Value example
You can also use the value property to render dates given as other types.
| Type | Expected format |
|---|---|
string | yyyy-dd-MM |
number | Epoch Unix Timestamp given in milliseconds |
Date | javascript Date object |
DateObjectValueShape | A DateObjectValueShape object |
<DateValue value={ "2025-01-15" } /> // string
<DateValue value={ 1736933400000 } /> // number
<DateValue value={ new Date('2025-01-15') } /> // Date object
<DateValue value={ { year: 2025, month: 1, day: 15 } } /> // DateObjectValueShape object
displayFormat examples
You can use the displayFormat property to choose a format to display the date.
<DateValue
value={ 1736933400000 }
displayFormat='vshort'
/>
<DateValue
value={ 1736933400000 }
displayFormat='short'
/>
<DateValue
value={ 1736933400000 }
displayFormat='long'
/>
<DateValue
value={ 1736933400000 }
displayFormat='abbreviated'
/>
<DateValue
value={ 1736933400000 }
displayFormat='full'
/>
Date and time example
The time component of any entered value will be ignored. To include the time, add an inputFormat string that designates a time component.
Note that you can use non-string values like number and DateObjectValueShape along with an inputFormat string to include times too.
// Without input format
<DateValue
value={ "2025-01-15 09:30" }
/>
// With input format
<DateValue
value={ "2025-01-15 09:30" }
inputFormat='yyyy-MM-dd hh:mm'
/>
// Number with input format
<DateValue
value={ 1736933400000 }
inputFormat='yyyy-MM-dd hh:mm'
/>
// DateObjectValueShape with input format
<DateValue
value={ {
year: 2025,
month: 0,
day: 15,
hour: 9,
minute: 30,
} }
inputFormat='yyyy-MM-dd hh:mm'
/>
Imperative API example
jutro-components offers the formatDate function for use with the imperative formatting API.
import { formatDate } from '@jutro/components';
import { IntlContext } from '@jutro/locale';
...
const intl = useContext(IntlContext);
...
const d1 = formatDate(intl, { value: { year: 2020, month: 2, day: 22, hour: 3, minute: 24 }, displayFormat: 'abbreviated' });
const d2 = formatDate(intl, { value: { year: 2020, month: 2, day: 22, hour: 3, minute: 24 }, displayFormat: 'full' })
const d3 = formatDate(intl, { }, { year: 2020, month: 2, day: 22, hour: 3, minute: 24 })
const d4 = formatDate(intl, { value: { year: 2020, month: 2, day: 22, hour: 3, minute: 24 }, displayFormat: 'abbreviated', inputFormat: 'yyyy/MM/dd hh:mm',});
const d5 = formatDate(intl, { value: { year: 2020, month: 2, day: 22, hour: 3, minute: 24 }, displayFormat: 'short'});
// en-US output:
Sun, Mar 22, 2020
Sunday, March 22, 2020
Mar 22, 2020
Sun, Dec 17, 1995, 03:24 AM
March 22, 2020
// pl-PL output
niedz., 22 mar 2020
niedziela, 22 marca 2020
22 mar 2020
niedz., 17 gru 1995, 03:24
22 marca 2020