Skip Navigation
Magma

Time Picker

Use the time input when you want the user to input a time in the format you choose. Enhanced keyboard navigation improves the general usability and accessibility of the component.

Basic Usage

import React from 'react';
import { TimePicker } from 'react-magma-dom';
export function Example() {
return <TimePicker labelText="Time Due" />;
}

Value

There are multiple formats you can send in through the value prop. You can do ##:## AM/PM and ##:## (which will default to 'AM' when the hour is less than 13 and 'PM' when between the hours of 13 and 23).

import React from 'react';
import { TimePicker } from 'react-magma-dom';
export function Example() {
return <TimePicker value="01:15 PM" labelText="Time Due" />;
}

Minutes Step

The minutesStep prop can be used to set the stepping interval when using the arrow keys on the minutes input. The default value is 1.

import React from 'react';
import { TimePicker } from 'react-magma-dom';
export function Example() {
return <TimePicker labelText="Time Due" minutesStep={15} />;
}

Error Message

If an input has an errorMessage, the input will be styled to highlight it's error state and the error message will appear below the input field. If an error message is present, it will replace the helper text. Can be a node or a string.

import React from 'react';
import { TimePicker } from 'react-magma-dom';
export function Example() {
return <TimePicker errorMessage="Invalid time" labelText="Time Due" />;
}

Helper Message

The helperMessage appears underneath the input field. It will not appear if an error message is present. Can be a node or a string.

import React from 'react';
import { TimePicker } from 'react-magma-dom';
export function Example() {
return <TimePicker helperMessage="Helper text" labelText="Time Due" />;
}

Inverse

import React from 'react';
import { Card, CardBody, TimePicker, magma } from 'react-magma-dom';
export function Example() {
return (
<Card background={magma.colors.neutral1100} isInverse>
<CardBody>
<TimePicker isInverse labelText="Time Due" />
</CardBody>
</Card>
);
}

OnChange Event

import React from 'react';
import { Card, CardBody, Paragraph, TimePicker } from 'react-magma-dom';
export function Example() {
const [timeValue, setTimeValue] = React.useState('');
const [onChangeCalledTimes, setOnChangeCalledTimes] = React.useState(0);
function handleOnChange(value) {
setTimeValue(value);
setOnChangeCalledTimes(onChangeCalledTimes + 1);
}
return (
<Card>
<CardBody>
<Paragraph>
<strong>Time Value:</strong> {timeValue}
</Paragraph>
<Paragraph>onChange called {onChangeCalledTimes} times</Paragraph>
<TimePicker labelText="Time Due" onChange={handleOnChange} />
</CardBody>
</Card>
);
}

Clear value

The value and onChange props can be used for clear value.

import React from 'react';
import { Button, TimePicker, Announce, VisuallyHidden } from 'react-magma-dom';
export function Example() {
const [timeValue, setTimeValue] = React.useState<string | undefined>('');
const [announcement, setAnnouncement] = React.useState('');
const [isCleared, setIsCleared] = React.useState(false);
const clearedText = 'Time has been cleared';
function handleOnChange(value) {
setAnnouncement(isCleared ? clearedText : '');
setTimeValue(value);
setIsCleared(false);
}
function onButtonClick() {
setIsCleared(timeValue ? true : false);
setTimeValue(undefined);
}
return (
<>
<TimePicker
labelText="Time Due"
onChange={handleOnChange}
value={timeValue}
/>
<br />
<Button onClick={onButtonClick}>Clear Time</Button>
<Announce>
<VisuallyHidden>{announcement}</VisuallyHidden>
</Announce>
</>
);
}

Custom Styles

The containerStyle, inputStyle, labelStyle and messageStyle props can be used for custom styling.

import React from 'react';
import { TimePicker } from 'react-magma-dom';
export function Example() {
return (
<TimePicker
containerStyle={{ border: '1px solid gray' }}
labelStyle={{ fontStyle: 'italic' }}
helperMessage="Helper text"
messageStyle={{ background: '#0000C7', color: '#FFFFFF' }}
inputStyle={{ border: '2px dotted black', width: '100%' }}
labelText="Time Due"
/>
);
}

Internationalization

The TimePicker component supports internationalization through the I18nContext. You can provide translations for the following properties hoursAriaLabel, minutesAriaLabel ,amButtonAriaLabel, pmButtonAriaLabel, amSelectedAnnounce and pmSelectedAnnounce Additionally, the labelText prop affects the aria-label of the input, ensuring that screen readers announce the correct label, making the component accessible for users in different languages.

import React from 'react';
import { zhCN } from 'date-fns/locale';
import { I18nContext, defaultI18n, TimePicker } from 'react-magma-dom';
export function Example() {
return (
<I18nContext.Provider
value={{
...defaultI18n,
locale: zhCN,
timePicker: {
hoursAriaLabel: '小时',
minutesAriaLabel: '分钟',
amButtonAriaLabel: '上午已选中。要切换到下午,请按 p 或回车键。',
pmButtonAriaLabel: '下午已选中。要切换到上午,请按 a 或回车键。',
amSelectedAnnounce: '现在选择上午',
pmSelectedAnnounce: '现在选择下午',
},
}}
>
<TimePicker labelText="到期时间" />
<TimePicker
labelText="International Time with Passed in Value"
value="01:30 下午"
/>
</I18nContext.Provider>
);
}

TimePicker Props

This component uses forwardRef. The ref is applied to the hidden input element that stores the value for full time value (hours, minutes, am/pm).

All of the standard input attributes can be provided as props and will be applied to the hidden input element that gets rendered.

actionable

Description

Is the wrapped input hidden with display:none? This would make the input look like an actionable item, so FormFieldContainer uses a span in lieu of a label.

Type

boolean

Default

-


containerStyle

Description

Style properties for the outer container

Type

CSSProperties

Default

-


disabled

Description

If true, the time picker cannot be edited.

Type

boolean

Default

false


errorMessage

Description

Content of the error message. If a value is provided, the field will be styled as an error state and the error message will display.

Type

ReactNode

Default

-


hasCharacterCounter

Description

Enables Character Counter by default. When set to false, the default HTML attribute of 'maxlength' will work. Note: This is a temporary prop and will be removed in future releases.

Type

boolean

Default

true


helperMessage

Description

Content of the helper message.

Type

ReactNode

Default

-


iconPosition

Description

Position within the component for the icon to appear

Type

enum, one of:
InputIconPosition.left
InputIconPosition.right
InputIconPosition.top

Default

InputIconPosition.right


id

Description

ID of the hidden input that stores the time value. Also the prefix for other fields.

Type

string

Default

-


inputLength

Description

Total number of characters in an input.

Type

number

Default

-


inputStyle

Description

Style properties for the outer input

Type

CSSProperties

Default

-


isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false


isLabelVisuallyHidden

Description

If true, label text will be hidden visually, but will still be read by assistive technology

Type

boolean

Default

false


labelPosition

Description

Position within the component for the label to appear

Type

enum, one of:
LabelPosition.left
LabelPosition.top

Default

LabelPosition.top


labelStyle

Description

Style properties for the label element

Type

CSSProperties

Default

-


labelText

Description

Content for label; can be a node or a string

Type

ReactNode

Default

-


labelWidth

Description

If the labelPosition value is 'left' then Input labels have a specified width in percentage, otherwise no width is set.

Type

number

Default

-


maxCount

Description

Enables the Character Counter and sets the maximum amount of characters allowed within the Input.

Type

number

Default

-


maxLength

Deprecated

Description

Enables the Character Counter and sets the maximum amount of characters allowed within the Input.

Type

number

Default

-


messageStyle

Description

Style properties for the helper or error message

Type

CSSProperties

Default

-


minutesStep

Description

Style properties for the label

Type

number

Default

-


onChange

Description

Function called when the component is changed to a new time

Type

function

Default

-


value

Description

Full time value passed in and converted to use in hour, minute, and AM/PM fields. To clear the TimePicker - send the undefined value.

Type

string

Default

-


On this page

Deploys by Netlify