Calendar

1.1.0

El patrón Calendar permite a los usuarios seleccionar fechas individuales o rangos de fechas dentro de una interfaz visual basada en un calendario. Es clave para flujos que requieren la definición de períodos temporales, como filtros, programación de eventos o gestión de contenidos. Su propósito es ofrecer una selección eficiente, clara y precisa de fechas. Calendar fue creado basado en ReactDayPicker y extiende sus propiedades, consultar la documentación para obtener una referencia completa de la API del 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;

Implementación

Instalá el componente via terminal.

npm install @nimbus-ds/calendar

Calendar

Cuándo usar

Usar el patrón Calendar cuando:

Se requiere seleccionar una única fecha o un rango definido.
El contexto incluye programación, reservas o visualización de datos históricos o futuros.
El usuario necesita contexto visual de fechas, como semanas, fines de semana o días deshabilitados.

Cuándo no usar

Evitar el uso del Calendar cuando:

La fecha es conocida y rápida de tipear, como fechas de nacimiento (usar input de texto con formato recomendado y validación).
Se necesita seleccionar solo el mes o el año sin granularidad diaria (usar selector de mes/año).
El dispositivo o flujo tiene espacio muy limitado (usar input de texto con validación).

Criterios de usabilidad y productividad

Preselección inteligente: mostrar fechas relevantes por defecto según el flujo (ej. hoy, esta semana).
Navegación con teclado: flechas para moverse entre días, tabulación lógica entre controles.
Feedback visual inmediato: resaltar la fecha seleccionada y el rango activo.
Persistencia de contexto: recordar la selección anterior entre aperturas consecutivas.
Submit con Enter: confirmar selección sin necesidad de click redundante.

Buenas prácticas de accesibilidad

Navegación completa con teclado (flechas, tab, Enter).
ARIA roles y atributos (role="grid", aria-selected, aria-label) para lectores de pantalla.
Áreas táctiles adecuadas en dispositivos mobiles (mínimo 44x44px).

Anatomía

El Calendar se compone de:

Selector de mes y año
Botones de navegación (prev/next)
Días del calendario
Estado de día (hoy, seleccionado, deshabilitado)
Área de selección de rango (opcional)
Text
Modal

Dependencias

Text
Button
Icon
Datepicker
Modal

Variantes

Single date: para una sola fecha.
Date range: para selección de períodos.
Modal with range selection: para selección de periodos y configuraciones mas complejas.

Do and Don'ts

✅ Do

Mostrar mes actual por defecto, centrado en el día de hoy.
Utilizar tooltips o texto alternativo para accesibilidad.
Resaltar la selección y permitir cambios con un solo click.
Ofrecer opción de limpiar fecha cuando sea útil.

❌ Don't

Mostrar múltiples meses sin necesidad: genera ruido visual.
Cambiar de mes sin animación: causa desorientación.
Forzar selección con doble click innecesario.
Usar colores sin soporte textual para señalar 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.