DatePicker
Com rótulo
Com limites
Vazio
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
| Prop | Tipo |
|---|---|
confirm0.5.0Rodape com Limpar e Aplicar. | boolean |
defaultValue0.4.0A data inicial, quando o componente controla o proprio estado. | Date | string |
disabledDays0.4.0Dias que nao podem ser escolhidos, nem no calendario nem digitados no campo. | Matcher[] | Matcher |
labelsOs 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.0O objeto de idioma usado para as datas. | Partial<DayPickerLocale> |
maxO ultimo dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`. | string | Date |
minO primeiro dia aceito, inclusive, em `Date` ou `aaaa-mm-dd`. | string | Date |
onValueChange0.4.0Chamado quando a data muda, pela digitacao ou pelo Aplicar. | ((date: Date | undefined) => void) | ((value: string) => void) |
render0.4.0Troca 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.0Mostra os dias de fora (os que caem no mês anterior ou no seguinte). | boolean |
size0.4.0Tamanho do campo, o mesmo vocabulario do Input. | "lg""md""sm" |
value0.4.0A 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.