Pular para o conteúdo
Formulário

DatePicker

/componentes/date-picker.mdmarkdown cru, para quem lê com agent em vez de olho

Com rótulo

Com limites

Vazio

Importar
import { DatePicker } from '@rivocode/ui'

Quando usar

Campo de data: dá para digitar e dá para escolher no calendário.

Digitar vem primeiro de propósito. Quem preenche formulário o dia inteiro digita 03032026 mais rápido do que navega três meses para trás.

Texto pela metade não vira data, e 31/02 não vira 3 de março. Ao sair do campo, o que não virou data fica no campo, marcado inválido e com a mensagem do motivo ligada por aria-describedby: incompleta, inexistente, fora da janela ou dia indisponível. O valor esvazia (undefined, ou "" em texto), para o formulário não enviar a data de antes com outra escrita na tela, e a peça não volta em silêncio para a data anterior: isso apagaria o que a pessoa digitou sem dizer por quê.

Dentro de <Field>, a mensagem vai para a validade do campo (setCustomValidity), e quem a mostra é o FieldError. Ao sair do campo com a data que não vale, a peça pede ao Field que valide na hora, seja qual for o validationMode: num Field sem Form, onde o onSubmit padrão nunca chegaria, o campo acende e o FieldError aparece do mesmo jeito. Fora dele, a peça mostra a mensagem logo abaixo. Os textos se trocam pelo labels.

Com readOnly, ou dentro de <Field disabled>, o botão do calendário fica desligado: somente leitura mostra a data e não deixa trocar por caminho nenhum.

Com confirm, o clique no dia vira rascunho e só o Aplicar escreve o valor. Ele nasce desligado aqui e ligado no DateRangePicker, e a diferença é de propósito: data única se escolhe num clique só, e período pede dois, o que faria um filtro sem rodapé recarregar duas vezes. No celular o painel vira folha de baixo, pelo CalendarPanel.

Valor

value e defaultValue aceitam Date ou texto aaaa-mm-dd, e o onValueChange responde no formato que recebeu. Em texto, a chamada é a mesma do @rivocode/ui-native:

const [vencimento, setVencimento] = useState<string | null>(null)

<DatePicker
  value={vencimento}
  onValueChange={setVencimento}
  min="2026-09-01"
  max="2026-12-31"
/>

Em texto, o campo que esvazia responde "", como o TimeField. Com Date, responde undefined, que é o que a peça sempre fez. Para começar vazio sem controlar o estado, defaultValue="" escolhe o formato de texto.

O texto é lido como dia do calendário, e não como instante: "2026-09-25" é 25 de setembro em qualquer fuso. O new Date("2026-09-25") do JavaScript lê meia-noite em UTC, que em Brasília ainda é dia 24, e é por isso que a peça nunca passa o texto por ele.

min e max são inclusivos. Valem para o calendário, que desabilita os dias de fora e para a navegação no mês de cada ponta, e para o que se digita: data fora da janela não chega ao onValueChange, e ao sair do campo fica marcada, com a mensagem dizendo o limite. disabledDays fica para o dia bloqueado avulso, como feriado, e vale do mesmo jeito para o que se digita.

Data e texto

As três funções que fazem a ponte com o Date saem pelo pacote, porque a tela que mostra data fora de um campo precisa das mesmas regras:

Função O que faz
formatDate(data) Date para dd/mm/aaaa, e string vazia quando não há data
parseDate(texto) dd/mm/aaaa para Date, e undefined para o que não é data
applyDateMask(texto) A máscara enquanto se digita: põe as barras e para em oito dígitos

parseDate devolve undefined para data que não existe. 31/02/2026 não vira 3 de março, que é o que o new Date faria sozinho e é a origem de metade dos vencimentos errados de um sistema de cobrança.

Tudo aqui trabalha na data local do navegador de propósito: a pessoa escolheu "3 de março" no calendário da tela dela, e não um instante em UTC.

Quando não usar

Para período de relatório ou de filtro, use DateRangePicker: o período é um valor só, com início e fim, e ele escolhe os dois no mesmo calendário. Para o mês na própria tela, sem campo, é o Calendar.

Hora do dia é TimeField, e compromisso com começo, fim e choque de horário é EventCalendar. E um MaskedInput com mask="data" não serve de atalho: perde o calendário e a validação da data.

No React Native

Traduz: o @rivocode/ui-native exporta DatePicker - abre a folha com o mês; guarda ISO aaaa-mm-dd, que o web também aceita, e exibe dd/mm/aaaa; disabledDays com o nome e as formas do web tira o fim de semana e a folga do calendário da folha. A API não é a mesma do web (no nativo tudo é controlado), e a tabela de paridade diz o que muda peça a peça.

API

PropTipo
confirm0.5.0

Rodape com Limpar e Aplicar.

boolean
defaultValue0.4.0

A data inicial, quando o componente controla o proprio estado.

Date | string
disabledDays0.4.0

Dias que nao podem ser escolhidos, nem no calendario nem digitados no campo.

Matcher[] | Matcher
labels

Os textos da peca, para trocar o idioma: `open` e o nome do botao do calendario, `title` o titulo do painel, `clear` e `apply` os dois botoes do rodape do `confirm`.

Partial<DatePickerLabels>
locale0.4.0

O objeto de idioma usado para as datas.

Partial<DayPickerLocale>
max

O ultimo dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`.

string | Date
min

O primeiro dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`.

string | Date
onValueChange0.4.0

Chamado quando a data muda, pela digitacao ou pelo Aplicar.

((date: Date | undefined) => void) | ((value: string) => void)
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldControlState> | ReactElement<unknown, string | JSXElementConstructor<any>>
showOutsideDays0.4.0

Mostra os dias de fora (os que caem no mês anterior ou no seguinte).

boolean
size0.4.0

Tamanho do campo, o mesmo vocabulario do Input.

"lg""md""sm"
value0.4.0

A data escolhida, quando quem usa controla o estado.

Datestringnull

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.