Time Picker

Campo de seleção de horário (24h) com digitação mascarada e dropdown de colunas para hora, minuto e segundo.

O mk-time-picker é o componente de seleção de horário do Makuco UI, sempre no formato 24h. Ele suporta entrada manual mascarada (apenas dígitos, com arredondamento automático de valores fora da faixa), seleção por um dropdown de colunas clicáveis e integração nativa com formulários via ElementInternals.

Quando usar

Use mk-time-picker para capturar horários em formulários, agendamentos e fluxos em que a entrada deve seguir um formato estruturado.

Use quando:

O usuário precisar informar um horário específico (hora e minuto, com segundos opcionais).
O fluxo exigir restrição a uma janela de horários válidos, como um expediente.
O formulário precisar de validação e envio nativo com name e required.

Prefira uma alternativa quando:

A necessidade for escolher uma data — use o mk-date-picker.
O valor exigir exibição em formato 12h (AM/PM) — o componente é exclusivo para 24h.

Padrão

import { MkTimePicker } from '@db1/makuco-ui-react';

<MkTimePicker label="Horário" name="time" />

<mk-time-picker label="Horário" name="time"></mk-time-picker>

Com segundos

Use showSeconds para exibir uma terceira coluna de segundos no dropdown e ajustar a máscara do campo para HH:mm:ss.

<MkTimePicker label="Horário" showSeconds />

<mk-time-picker label="Horário" show-seconds></mk-time-picker>

Validação ao digitar

A digitação manual usa a máscara time do mk-input: apenas dígitos são aceitos e cada segmento (hora, minuto, segundo) é validado enquanto o usuário digita, em vez de só no envio do formulário.

Um primeiro dígito que nunca formaria uma dezena válida fecha o segmento sozinho, completado com zero à esquerda. Digitar 3 na hora vira 03 e o campo avança para o minuto.
Uma combinação que ultrapassaria o máximo do segmento é rejeitada. Com a hora já em 2, digitar 7 (formaria 27, inválido) não tem efeito — a hora permanece 2, aguardando um dígito de 0 a 3.
A mesma regra vale para minutos e segundos (máximo 59): digitar 7 sozinho no minuto fecha como 07.

Intervalo permitido (min/max)

Use min e max (formato HH:mm) para desabilitar horas e minutos fora do intervalo permitido no dropdown.

<MkTimePicker label="Horário de expediente" min="08:00" max="18:00" />

<mk-time-picker label="Horário de expediente" min="08:00" max="18:00"></mk-time-picker>

Intervalo entre opções (step)

Use step para controlar o intervalo em minutos entre as opções de minuto e segundo no dropdown.

<MkTimePicker label="Horário (intervalos de 15 min)" step={15} />

<mk-time-picker label="Horário (intervalos de 15 min)" step="15"></mk-time-picker>

Texto de suporte

Use supportText para exibir uma instrução ou dica complementar abaixo do campo. Quando errorMessage está definido, o texto de suporte é substituído pela mensagem de erro.

<MkTimePicker label="Horário" supportText="Selecione um horário no formato HH:mm" />

<mk-time-picker label="Horário" support-text="Selecione um horário no formato HH:mm"></mk-time-picker>

Somente leitura

Use readonly para exibir o horário selecionado sem permitir edição. O ícone de relógio torna-se decorativo e o popover não abre.

<MkTimePicker label="Horário" readonly value="14:30" />

<mk-time-picker label="Horário" readonly value="14:30"></mk-time-picker>

Estado de erro

Defina errorMessage para ativar o estado de erro.

<MkTimePicker label="Horário" errorMessage="Horário fora do expediente" />

<mk-time-picker label="Horário" error-message="Horário fora do expediente"></mk-time-picker>

Desabilitado

Use disabled quando a seleção não deve estar disponível para o usuário em determinado contexto.

<MkTimePicker label="Horário" disabled value="14:30" />

<mk-time-picker label="Horário" disabled value="14:30"></mk-time-picker>

Props

Prop	Tipo	Padrão	Descrição
`label`	`string`	—	Texto do rótulo exibido acima do campo. É obrigatório para acessibilidade.
`name`	`string`	—	Nome do campo para envio em formulários nativos.
`value`	`string`	—	Horário selecionado, sempre 24h (`HH:mm` ou `HH:mm:ss`).
`showSeconds`	`boolean`	`false`	Exibe a coluna de segundos no dropdown e ajusta a máscara do campo para `HH:mm:ss`.
`step`	`number`	`1`	Intervalo em minutos entre as opções de minuto e segundo no dropdown.
`min`	`string`	—	Horário mínimo permitido (`HH:mm`). Opções fora do intervalo ficam desabilitadas.
`max`	`string`	—	Horário máximo permitido (`HH:mm`).
`errorMessage`	`string`	—	Mensagem exibida abaixo do campo quando o estado é inválido.
`supportText`	`string`	—	Texto de suporte exibido abaixo do campo quando não há erro.
`disabled`	`boolean`	`false`	Impede qualquer interação com o componente.
`readonly`	`boolean`	`false`	Exibe o valor sem permitir edição. O popover não abre e o ícone de relógio torna-se decorativo.
`required`	`boolean`	`false`	Marca o campo como obrigatório em formulários.
`requiredMessage`	`string`	`"Este campo é obrigatório"`	Mensagem de validação nativa usada quando `required` está ativo e o campo está vazio. Substitua para suporte a i18n.

Eventos

Evento	Payload	Descrição
`mkChange`	`string`	Emitido ao selecionar um horário completo nas colunas ou ao digitar um horário válido. Sempre no formato `HH:mm` ou `HH:mm:ss`.
`mkOpen`	`void`	Emitido quando o popover de seleção abre.
`mkClose`	`void`	Emitido quando o popover de seleção fecha.
`mkFocus`	`void`	Emitido quando o campo recebe foco.
`mkBlur`	`void`	Emitido quando o campo perde o foco.

Acessibilidade

O campo deve sempre receber um label claro e descritivo.
O campo expõe aria-haspopup="listbox", aria-expanded e aria-controls para descrever o popover de seleção.
O popover é anunciado como role="dialog" e cada coluna (hora/minuto/segundo) é uma role="listbox" navegável, com opções em role="option".
Opções fora do intervalo de min/max recebem aria-disabled.
Escape e Tab fecham o popover; clicar fora também fecha.
A digitação manual é validada em tempo real pela máscara do campo: apenas dígitos são aceitos e valores fora da faixa (ex: hora 31) são arredondados para o valor completo mais próximo (ex: 03) em vez de aceitos como estão.

Time Picker

On this page