Skip to content
Block Kit for React
Esc
↑↓navigate↵open⌘Jpreview
On this page

Time picker element

A dropdown list for choosing a time of day, rendered like Slack's timepicker.

timepicker is a field you can type a time into, with a list of the day’s hours under it. Use it in an actions block or a section’s accessory for a quick pick, or in an input block to collect a time in a modal.

Like Slack’s, the field is a text input (role="combobox"). Clicking it opens the list, hour by hour from 12:00 AM, with nothing highlighted; reopened, the field holds the chosen time as selected text, so typing replaces it. As in Slack, typing doesn’t filter or highlight the list: Enter reads what you typed, so 2:15 PM, 2:15pm or 14:15 is picked and sent as typed ("14:15"), and text that isn’t a time is ignored, leaving the list open. The arrow keys highlight a row (the first press starts at 12:00 AM), Enter picks the highlighted time over anything typed, and Escape or Tab closes the list and puts the chosen time back. A time picked with Enter leaves the field focused; a clicked time leaves nothing focused, as in Slack, so the field drops its focus ring.

Your AppAPP
onActionInteract with the preview.

Fields

PropType
typestring

Always timepicker.

Typestring
action_id?string

Identifies this element in the block_actions payload. Must be unique within a block.

Typestring
initial_time?string

The time selected when the element loads, as 24-hour HH:mm, e.g. 22:25 for 10:25pm.

Typestring
timezone?string

An IANA time zone, e.g. America/Chicago. Shown as hint text under the control and passed back on interaction.

Typestring
placeholder?PlainTextElement

Text shown when no time is selected. Slack limits it to 150 characters.

TypePlainTextElement
confirm?ConfirmationDialog

A confirmation dialog shown before the pick takes effect.

TypeConfirmationDialog
focus_on_load?boolean

Focuses this element when its modal or Home tab loads. Only one element per view. Slack ignores it in messages.

Typeboolean
Defaultfalse

Like Slack, the field comes in two sizes: the compact 28px field in messages, and the 36px field with 15px text in modals and on App Home.

Examples

Without an initial value

Your AppAPP
onActionInteract with the preview.

The closed control shows the placeholder text, or “Time” if none is given, until a time is picked. Then it reads e.g. “1:37 PM”.

With an initial value

Your AppAPP
onActionInteract with the preview.

Inside an input block

Your AppAPP
Label

With a time zone

Setting timezone shows a hint underneath the control naming the zone the way Slack does, after its own region list rather than the IANA id: America/New_York reads “Time zone: Eastern Time (US and Canada)”, Europe/Madrid “Time zone: Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna”, and UTC “Time zone: Monrovia, Reykjavik”. The names were recorded from Block Kit Builder for every zone browsers know; a zone it doesn’t name shows its IANA id. The hint is all timezone changes: selected_time is the HH:mm the user picked, as Slack sends it. The provider’s timeZone doesn’t apply to a time picker.

Your AppAPP
Time zone: Pacific Time (US and Canada)
onActionInteract with the preview.

timezone is a display hint only: it labels the picker but doesn’t shift initial_time or the options list, which are always plain HH:mm wall-clock values. It’s unrelated to the timeZone prop on BlockKitProvider, which controls how other elements (like datetimepicker) format their values for display.

With a confirmation dialog

Your AppAPP
onActionInteract with the preview.

Interactivity

Picking a time, from the list or typed, fires an action with selected_time. In an input block, the list is as wide as the field. Where the time may be left empty (an optional input block, or any input block in a message), the list starts with “Clear selection” once a time is set, and clearing sends null:

{
  "type": "timepicker",
  "action_id": "select_time",
  "block_id": "meeting",
  "selected_time": "15:00"
}

The same shape lands in state.values[block_id][action_id]:

{
  "type": "timepicker",
  "selected_time": "15:00"
}

When initial_time is set, the action carries it too ("initial_time": "13:37"), as Slack’s does. It’s also reported as state as soon as the element mounts, before any interaction.

Last updated on