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.

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;

Instalá el componente via terminal.

npm install @nimbus-ds/calendar

Calendar

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.

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).
  • 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.
  • 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).

El Calendar se compone de:

  1. Selector de mes y año
  2. Botones de navegación (prev/next)
  3. Días del calendario
  4. Estado de día (hoy, seleccionado, deshabilitado)
  5. Área de selección de rango (opcional)
  6. Text
  7. Modal
  • Text
  • Button
  • Icon
  • Datepicker
  • Modal
  • 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

  • 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.

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

Calendar

NameTypeDefaultDescription

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.