Date and time value

Examples

Check out the Usage section for details about how to design a date value properly, and the different configuration options we provide.

Basic 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

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
string
Description
CSS class name for this component.
date: Type
Date
Description
Date value override to be used instead of the one provided with props.
displayFormat: Type
'vshort' | 'short' | 'long' | 'abbreviated' | 'full'
Description
The date format used to display the date.
id: Type
string
Description
Unique identifier for the component.
inputFormat: Type
string
Description
Format of the date displayed when the value is edited. Used to retrieve tokens that will be displayed.
path: Type
string
Description
Specifies the path to the value used to generate the output.
placeholder: Type
IntlMessageShape
Description
The string to display if 'date' is undefined/null.
prefix: Type
IntlMessageShape
Description
Optional prefix message to be attached before the value.
skipTimeZone: Type
boolean
Description
If set to true, the date won't be converted to defaultTimezone. Use if the date is already converted to the desired time zone.
suffix: Type
IntlMessageShape
Description
Optional suffix message to be attached after the value.
tag: Type
string
Description
The HTML tag to use when rendering the outermost element of this component.

Default value
'div'
value: Type
string | number | Date | DateObjectValueShape
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
number
Description
Years counting from 0 CE.
day: Type
number
Description
The day of the month. Max value depends on the month and whether it is a leap year.
hour: Type
number
Description
Hour of the day, following the 24 hour clock. Must be between 0 and 23 inclusive.
minute: Type
number
Description
Minute of the hour. Must be between 0 and 59 inclusive.
month: Type
number
Description
Month 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
string
Description
Formatted date string.
date: Type
string | number | Date | DateObjectValueShape
Description
Date value override to be used instead of the one provided with props.
intl: Type
react.intl.Intl
Description
An instance of the imperative formatting API access object.
props: Type
DateValue.propTypes
Description
Valid properties for a DateValue object.

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.

Date and time value

Examples

Basic example

Value example

`displayFormat` examples

Date and time example

Imperative API example

Usage

Code

Import statement

Component contract

Properties

`className`

`date`

`displayFormat`

`id`

`inputFormat`

`path`

`placeholder`

`prefix`

`skipTimeZone`

`suffix`

`tag`

`value`

`DateObjectValueShape`

`year`required

`day`

`hour`

`minute`

`month`

Valid formats for value property

Imperative API

Return value

`date`

`intl`

`props`

Hooks

Translation keys

Escape hatches

Changelog

Examples​

Basic example​

Value example​

displayFormat examples​

Date and time example​

Imperative API example​

Usage​

Code​

Import statement​

Component contract​

Properties​

className​

date​

displayFormat​

id​

inputFormat​

path​

placeholder​

prefix​

skipTimeZone​

suffix​

tag​

value​

DateObjectValueShape​

yearrequired​

day​

hour​

minute​

month​

Valid formats for value property​

Imperative API​

Return value​

date​

intl​

props​

Hooks​

Translation keys​

Escape hatches​

Changelog​

Examples

Basic example

Value example

`displayFormat` examples

Date and time example

Imperative API example

Usage

Code

Import statement

Component contract

Properties

`className`

`date`

`displayFormat`

`id`

`inputFormat`

`path`

`placeholder`

`prefix`

`skipTimeZone`

`suffix`

`tag`

`value`

`DateObjectValueShape`

`year`required

`day`

`hour`

`minute`

`month`

Valid formats for value property

Imperative API

Return value

`date`

`intl`

`props`

Hooks

Translation keys

Escape hatches

Changelog