DatePicker

O DatePicker é um componente para seleção de datas únicas, ideal para campos como data de nascimento, agendamentos, prazos e vencimentos. Oferece uma interface intuitiva com calendário e suporte a internacionalização.

Importação

import { DatePicker } from '@useblu/ocean-react';

Importação específica (recomendado para tree-shaking)

import { DatePicker } from '@useblu/ocean-react/DatePicker';

Importação de tipos TypeScript

import type { DatePickerSingleProps } from '@useblu/ocean-react';

// Uso em componente customizado
const MyDatePicker: React.FC<DatePickerSingleProps> = (props) => {
  return <DatePicker {...props} />;
};

Playground Interativo

Explore o componente DatePicker no playground interativo do Storybook:

🚀 Abrir no Storybook

Documentação Completa

Para documentação técnica detalhada, exemplos de uso e API completa, consulte o Storybook do DatePicker.

No Storybook você encontrará:

✅ Controles interativos para testar todas as props
✅ API gerada automaticamente com tipagem completa
✅ Exemplos visuais de todas as variações e estados
✅ Playground para experimentação rápida

Uso básico

import { useState } from 'react';

function BasicDatePicker() {
  const [date, setDate] = useState('');

  return (
    <DatePicker label="Selecione uma data" value={date} onSelect={setDate} />
  );
}

Estados do Componente

Normal

import { useState } from 'react';

function NormalDatePicker() {
  const [date, setDate] = useState('');

  return <DatePicker label="Data normal" value={date} onSelect={setDate} />;
}

Com erro

import { useState } from 'react';

function ErrorDatePicker() {
  const [date, setDate] = useState('');

  return (
    <DatePicker
      label="Data obrigatória"
      value={date}
      onSelect={setDate}
      error={true}
      helperText="Este campo é obrigatório"
    />
  );
}

Desabilitado

<DatePicker
  label="Data desabilitada"
  value=""
  onSelect={() => {}}
  disabled={true}
/>

Estados Visuais

Veja todos os estados do DatePicker:

🚀 Abrir no Storybook

Funcionalidades Especiais

Campo editável

import { useState } from 'react';

function EditableDatePicker() {
  const [date, setDate] = useState('');

  return (
    <DatePicker
      label="Data editável"
      value={date}
      onSelect={setDate}
      editable
      helperText="Você pode digitar a data ou usar o calendário"
    />
  );
}

Limitando a partir de hoje

import { useState } from 'react';

function FutureDatePicker() {
  const [date, setDate] = useState('');

  return (
    <DatePicker
      label="Data do agendamento"
      value={date}
      onSelect={setDate}
      startsToday
      helperText="Selecione uma data a partir de hoje"
      disabledDays={(current) => current < new Date()}
    />
  );
}

Restrições e Validações

Veja exemplos com diferentes restrições:

🚀 Abrir no Storybook

Bloqueando períodos específicos

Use a prop disabledDays para impedir que o usuário selecione intervalos inteiros (por exemplo, feriados ou períodos de manutenção). Você pode combinar disabledDays com startsToday ou passar uma lista de Matchers para cobrir várias faixas.

import { useState } from 'react';

const createDate = (year: number, month: number, day: number) =>
  new Date(year, month - 1, day);

const blackout = [
  { from: createDate(2026, 3, 9), to: createDate(2026, 3, 12) },
  { from: createDate(2026, 7, 1), to: createDate(2026, 7, 7) },
];

function BlockedDatePicker() {
  const [date, setDate] = useState('');

  return (
    <DatePicker
      label="Datas bloqueadas"
      value={date}
      onSelect={setDate}
      startsToday
      disabledDays={blackout}
      helperText="Evita períodos críticos"
    />
  );
}

Veja essa configuração em ação no story "Sem fins de semana" (inclui disabledDays com ranges):

🚀 Abrir no Storybook

Quando um usuário tenta selecionar um dia bloqueado, você pode exibir uma mensagem explicativa através da prop disabledDaysMessage. O tooltip aparece automaticamente ao clicar em um dia desabilitado e desaparece após 5 segundos.

A prop aceita dois formatos:

string — mesma mensagem para todos os dias bloqueados
{ date: Date; message: string }[] — mensagem específica por data; dias bloqueados sem entrada no array não exibem tooltip

Mensagem fixa para todos os dias bloqueados

import { useState } from 'react';

function DatePickerWithTooltip() {
  const [date, setDate] = useState('');

  return (
    <DatePicker
      label="Datas úteis"
      value={date}
      onSelect={setDate}
      disabledDays={[
        { dayOfWeek: [0, 6] }, // Fins de semana
        { before: new Date() }, // Datas passadas
      ]}
      disabledDaysMessage="Boletos pagos em finais de semana, feriados ou após às 16:00 são quitados no próximo dia útil."
      helperText="Tente clicar em um dia bloqueado para ver o tooltip"
    />
  );
}

🚀 Abrir no Storybook

Mensagem específica por data

Passe um array com entradas { date, message } para exibir uma mensagem diferente em cada data bloqueada. Clique em uma data que não tem entrada no array — nenhum tooltip é exibido.

import { useState } from 'react';

const addDays = (n) => {
  const d = new Date();
  d.setDate(d.getDate() + n);
  return d;
};

const blockedDates = [
  { date: addDays(3), message: 'Manutenção programada neste dia' },
  { date: addDays(7), message: 'Feriado municipal' },
  { date: addDays(10), message: 'Bloqueio operacional' },
];

function DatePickerWithListMessages() {
  const [date, setDate] = useState('');

  return (
    <DatePicker
      label="Selecione uma data"
      value={date}
      onSelect={setDate}
      disabledDays={blockedDates.map((e) => e.date)}
      disabledDaysMessage={blockedDates}
      helperText="Clique nos dias marcados para ver o motivo"
    />
  );
}

🚀 Abrir no Storybook

Internacionalização

O DatePicker suporta diferentes idiomas através do date-fns:

🚀 Abrir no Storybook

Configuração de idiomas

import { ptBR, enUS } from 'date-fns/locale';

// Português (padrão)
<DatePicker
  label="Data"
  value={date}
  onSelect={setDate}
  locale={ptBR}
/>

// Inglês
<DatePicker
  label="Date"
  value={date}
  onSelect={setDate}
  locale={enUS}
/>

Casos de Uso Práticos

Informações pessoais

import { useState } from 'react';

function PersonalInfoForm() {
  const [birthDate, setBirthDate] = useState('');
  const [startDate, setStartDate] = useState('');

  return (
    <div>
      <DatePicker
        label="Data de nascimento"
        value={birthDate}
        onSelect={setBirthDate}
      />

      <DatePicker
        label="Data de admissão"
        value={startDate}
        onSelect={setStartDate}
        helperText="Data de início na empresa"
      />
    </div>
  );
}

Agendamentos

import { useState } from 'react';

function AppointmentForm() {
  const [appointmentDate, setAppointmentDate] = useState('');

  return (
    <DatePicker
      label="Data da consulta"
      value={appointmentDate}
      onSelect={setAppointmentDate}
      startsToday
      helperText="Selecione uma data disponível"
    />
  );
}

Prazos e vencimentos

import { useState } from 'react';

function DeadlineForm() {
  const [deadline, setDeadline] = useState('');
  const [deliveryDate, setDeliveryDate] = useState('');

  return (
    <div>
      <DatePicker
        label="Data de vencimento"
        value={deadline}
        onSelect={setDeadline}
        startsToday
      />

      <DatePicker
        label="Prazo de entrega"
        value={deliveryDate}
        onSelect={setDeliveryDate}
        editable
        helperText="Digite ou selecione a data"
      />
    </div>
  );
}

Validação

Implementação de validação

import { useState } from 'react';

function ValidatedDatePicker() {
  const [date, setDate] = useState('');
  const [error, setError] = useState(false);

  const handleSelect = (selectedDate: string) => {
    setDate(selectedDate);
    setError(!selectedDate); // Erro se não há data selecionada
  };

  return (
    <DatePicker
      label="Data obrigatória"
      value={date}
      onSelect={handleSelect}
      error={error}
      helperText={error ? 'Este campo é obrigatório' : 'Data válida'}
    />
  );
}

API

Props

Prop	Tipo	Padrão	Descrição
`label`	`string`	-	Label do campo de entrada
`value`	`string`	-	Valor da data selecionada (obrigatório)
`onSelect`	`(date: string) => void`	-	Função chamada ao selecionar data (obrigatório)
`editable`	`boolean`	`false`	Permite edição manual do campo
`disabled`	`boolean`	`false`	Desabilita o componente
`error`	`boolean`	`false`	Exibe estado de erro
`helperText`	`string`	-	Texto de ajuda ou erro
`startsToday`	`boolean`	`false`	Limita seleção a partir da data atual
`disabledDays`	`Matcher` \| `Matcher[]` \| `(date: Date) => boolean`	-	Bloqueia datas específicas no calendário
`disabledDaysMessage`	`string \| { date: Date; message: string }[]`	-	Mensagem fixa ou lista de mensagens por data para dias bloqueados
`inline`	`boolean`	`false`	Exibe o calendário aberto sem o campo de input
`locale`	`Locale`	`ptBR`	Locale do date-fns para internacionalização
`className`	`string`	-	Classes CSS adicionais

A prop disabledDays aceita Matchers ({ from, to }, before, after, dayOfWeek, etc.) ou uma função para regras personalizadas. Combine-a com startsToday para criar restrições complexas sem precisar mexer no componente.

disabledDaysMessage como array: dias bloqueados sem entrada correspondente no array não exibem tooltip. Use para comunicar motivos distintos por data (feriados, manutenções, bloqueios operacionais, etc.).

Eventos

onSelect: Disparado quando uma data é selecionada no calendário

Acessibilidade

✅ Navegação por teclado: Suporte completo para Tab, setas, Enter e Escape
✅ Screen readers: Labels e estados anunciados corretamente
✅ Foco visual: Indicação clara do elemento focado
✅ ARIA attributes: Implementação correta de atributos ARIA
✅ Contraste: Cores adequadas para diferentes níveis de visão

Navegação por teclado

Tecla	Função
`Tab`	Navega entre elementos
`Space` / `Enter`	Abre/fecha calendário
`Setas`	Navega entre datas no calendário
`Page Up/Down`	Navega entre meses
`Home/End`	Vai para início/fim da semana
`Escape`	Fecha o calendário

Melhores Práticas

✅ Faça

Use DatePicker para seleção de datas únicas
Configure startsToday para datas futuras obrigatórias
Forneça helperText explicativo para orientar o usuário
Use locale apropriado para seu público-alvo
Implemente validação com estado error
Use labels descritivos que expliquem o propósito

❌ Não faça

Não use DatePicker para intervalos de datas (use DateRange)
Não omita onSelect ou value (props obrigatórias)
Não ignore validação de datas inválidas
Não use textos de erro genéricos sem contexto
Não desabilite sem explicar o motivo no helperText

Quando Usar

✅ Ideal para:

Datas de nascimento e informações pessoais
Prazos e vencimentos únicos
Agendamentos de eventos pontuais
Datas de contrato e documentos
Marcos e milestones específicos

❌ Evite para:

Seleção de intervalos de datas (use DateRange)
Seleção de horários (use TimePicker dedicado)
Múltiplas datas não contínuas
Datas muito distantes sem navegação otimizada

CSS Classes

O componente gera as seguintes classes CSS:

Classe	Descrição
`.ods-date`	Classe base aplicada ao componente
`.ods-date__calendar`	Container do calendário modal
`.ods-date__caption-single`	Título do mês no DatePicker
`.ods-date__navButtons`	Container dos botões de navegação
`.ods-date__navButtonPrev`	Botão de mês anterior
`.ods-date__navButtonNext`	Botão de próximo mês
`.ods-date__navIcon`	Ícone dos botões de navegação
`.ods-date__table`	Tabela do calendário
`.ods-date__head`	Cabeçalho da tabela (dias da semana)
`.ods-date__body`	Corpo da tabela (dias do mês)
`.ods-date__row`	Linha da tabela
`.ods-date__cell`	Célula da tabela
`.ods-date__day`	Elemento do dia
`.ods-date__today`	Dia atual destacado
`.ods-date__selected`	Dia selecionado
`.ods-date__disabled`	Dias desabilitados

Links relacionados

DateRange - Para seleção de intervalos de datas
Input - Para entrada de dados base
FormControl - Para controle de formulários
Storybook - DatePicker - Documentação técnica

Importação​

Importação específica (recomendado para tree-shaking)​

Importação de tipos TypeScript​

Playground Interativo​

Documentação Completa​

Uso básico​

Estados do Componente​

Normal​

Com erro​

Desabilitado​

Estados Visuais​

Funcionalidades Especiais​

Campo editável​

Limitando a partir de hoje​

Restrições e Validações​

Bloqueando períodos específicos​

Mensagem de tooltip para dias bloqueados​

Mensagem fixa para todos os dias bloqueados​

Mensagem específica por data​

Internacionalização​

Configuração de idiomas​

Casos de Uso Práticos​

Informações pessoais​

Agendamentos​

Prazos e vencimentos​

Validação​

Implementação de validação​

API​

Props​

Eventos​

Acessibilidade​

Navegação por teclado​

Melhores Práticas​

✅ Faça​

❌ Não faça​

Quando Usar​

✅ Ideal para:​

❌ Evite para:​

CSS Classes​

Links relacionados​

Importação

Importação específica (recomendado para tree-shaking)

Importação de tipos TypeScript

Playground Interativo

Documentação Completa

Uso básico

Estados do Componente

Normal

Com erro

Desabilitado

Estados Visuais

Funcionalidades Especiais

Campo editável

Limitando a partir de hoje

Restrições e Validações

Bloqueando períodos específicos

Mensagem de tooltip para dias bloqueados

Mensagem fixa para todos os dias bloqueados

Mensagem específica por data

Internacionalização

Configuração de idiomas

Casos de Uso Práticos

Informações pessoais

Agendamentos

Prazos e vencimentos

Validação

Implementação de validação

API

Props

Eventos

Acessibilidade

Navegação por teclado

Melhores Práticas

✅ Faça

❌ Não faça

Quando Usar

✅ Ideal para:

❌ Evite para:

CSS Classes

Links relacionados