Calendar

1.1.0

O padrão Calendar permite aos usuários selecionar datas individuais ou intervalos de datas dentro de uma interface visual baseada em um calendário. É chave para fluxos que requerem a definição de períodos temporais, como filtros, programação de eventos ou gestão de conteúdos. Seu propósito é oferecer uma seleção eficiente, clara e precisa de datas. Calendar foi criado baseado em ReactDayPicker e estende suas propriedades, consulte a documentação para obter uma referência completa da API do componente.

Default

Date picker

Modal with range selection

import React, { useState } from "react";
import { Calendar } from "@nimbus-ds/patterns";
import { Box, Text } from "@nimbus-ds/components";
import { format } from "date-fns";

const Example: React.FC = () => {
  const today = new Date();
  const [selectedDate, setSelectedDate] = useState<Date | undefined>();
  const [month, setMonth] = useState<Date>(today);

  return (
    <Box
      width="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
      flexDirection="column"
      gap="2"
    >
      <Calendar
        mode="single"
        showOutsideDays
        selected={selectedDate}
        onSelect={setSelectedDate}
        toDate={today}
        month={month}
        onMonthChange={setMonth}
        containerProps={{
          height: "100%",
          overflowY: "auto",
          maxHeight: "400px",
        }}
      />
      {selectedDate ? (
        <Text>Selected date is {format(selectedDate, "dd-MM-yyyy")}</Text>
      ) : (
        <Text>Select a date</Text>
      )}
    </Box>
  );
};

export default Example;

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/calendar

Calendar

Quando usar

Usar o padrão Calendar quando:

Se requer selecionar uma única data ou um intervalo definido.
O contexto inclui programação, reservas ou visualização de dados históricos ou futuros.
O usuário necessita contexto visual de datas, como semanas, fins de semana ou dias desabilitados.

Quando não usar

Evitar o uso do Calendar quando:

A data é conhecida e rápida de digitar, como datas de nascimento (usar input de texto com formato recomendado e validação).
Se necessita selecionar apenas o mês ou o ano sem granularidade diária (usar seletor de mês/ano).
O dispositivo ou fluxo tem espaço muito limitado (usar input de texto com validação).

Critérios de usabilidade e produtividade

Pré-seleção inteligente: mostrar datas relevantes por padrão segundo o fluxo (ex. hoje, esta semana).
Navegação com teclado: setas para mover-se entre dias, tabulação lógica entre controles.
Feedback visual imediato: destacar a data selecionada e o intervalo ativo.
Persistência de contexto: lembrar a seleção anterior entre aberturas consecutivas.
Submit com Enter: confirmar seleção sem necessidade de clique redundante.

Boas práticas de acessibilidade

Navegação completa com teclado (setas, tab, Enter).
ARIA roles e atributos (role="grid", aria-selected, aria-label) para leitores de tela.
Áreas táteis adequadas em dispositivos móveis (mínimo 44x44px).

Anatomia

O Calendar se compõe de:

Seletor de mês e ano
Botões de navegação (anterior/próximo)
Dias do calendário
Estado do dia (hoje, selecionado, desabilitado)
Área de seleção de intervalo (opcional)
Text
Modal

Dependências

Text
Button
Icon
Datepicker
Modal

Variantes

Single date: para uma única data.
Date range: para seleção de períodos.
Modal with range selection: para seleção de períodos e configurações mais complexas.

Do and Don'ts

✅ Do

Mostrar mês atual por padrão, centrado no dia de hoje.
Utilizar tooltips ou texto alternativo para acessibilidade.
Destacar a seleção e permitir mudanças com um único clique.
Oferecer opção de limpar data quando for útil.

❌ Don't

Mostrar múltiplos meses sem necessidade: gera ruído visual.
Mudar de mês sem animação: causa desorientação.
Forçar seleção com duplo clique desnecessário.
Usar cores sem suporte textual para sinalizar estados.

Props

Additional props are passed to the <Calendar> element. See div docs for a list of props accepted by the <Calendar> element.

Calendar

Name	Type	Description
hideBorder	boolean	Ability to hide the border of the calendar container. Useful for including the calendar inside other components such as Modal, Popover or Card.
stickyWeekdays	boolean	If true will stick the weekday indicators to the top of the component. Useful for when creating scrolling calendars with a display of >1 months. Only works when property numberOfMonths is set to a number greater than 1.
fullWidthDays	boolean	If true the buttons for individual days will span 100% of available width as opposed to the default state where they have a fixed width. Useful for when creating calendars inside containers that are wider than default.