Datepicker

Overview

The Datepicker component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Date selection is error-prone with free-text inputs. A datepicker enforces format, provides visual calendar context, and prevents invalid dates.

Mental model

When to use

When not to use

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

import { useState } from 'react';
import { Datepicker } from '@byteion/react';

export default function DatepickerDemo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <div className="grid max-w-md gap-4 p-6">
      <Datepicker label="Start date" value={value} onChange={setValue}
        placeholder="Pick a date" />
      <Datepicker label="With min" min={new Date()} placeholder="Future only" />
    </div>
  );
}

<script setup lang="ts">
import { ref } from 'vue';
import { Datepicker } from '@byteion/vue';

const date = ref<Date | null>(null);
</script>

<template>
  <div class="grid max-w-md gap-4 p-6">
    <Datepicker v-model="date" label="Start date" placeholder="Pick a date" />
    <Datepicker label="With min" :min="new Date()" placeholder="Future only" />
  </div>
</template>

States

This component reacts seamlessly to the following interaction and data states:

• default — Resting appearance before interaction.
• hover — Pointer is over the element — visual feedback via color or shadow.
• focus — Keyboard or tab focus — shows ring indicator for accessibility.
• active — Currently selected or in use.
• disabled — Non-interactive — grayed out, cursor not-allowed.
• loading — Action in progress — spinner replaces icon, button is disabled.
• open — Component is expanded or visible.
• closed — Component is collapsed or hidden.

Anatomy

Usage guidelines

• Show format hint (MM/DD/YYYY).
• Highlight today and selected date.
• Disable dates outside the valid range.

Do and Don't

Accessibility

Calendar grid uses arrow keys for navigation. Selected date has aria-selected.

Customization

Selected date color follows --primary.

import { cva, cn, type VariantProps } from '@byteion/react';

const myDatepicker = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myDatepicker>;

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myDatepicker = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myDatepicker({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX

API Reference

Uses data attributes for toggle and date selection.

export interface DatepickerProps {
  /** Controlled date (YYYY-MM-DD). */
  value?: string | null;
  defaultValue?: string | null;
  onValueChange?: (value: string | null) => void;
  label?: ReactNode;
  helperText?: ReactNode;
  error?: ReactNode;
  placeholder?: string;
  disabled?: boolean;
  /** Format the date in the input. Default is the raw ISO string. */
  format?: (value: string) => string;
  /** Initial month when opening with no value. */
  initialMonth?: number;
  initialYear?: number;
  /** Render the calendar popup open initially. Useful for documentation showcases. */
  defaultOpen?: boolean;
  /** Limit the popup preview to N weeks. Primarily for docs parity. */
  compactWeeks?: number;
  /** Skip leading day cells in a curated compact preview. */
  compactStartOffset?: number;
  id?: string;
  className?: string;
  /** Minimum selectable date (ISO YYYY-MM-DD). */
  min?: string;
  /** Maximum selectable date (ISO YYYY-MM-DD). */
  max?: string;
  name?: string;
  'data-bi-date-range-start'?: boolean;
  'data-bi-date-range-end'?: boolean;
}

export interface DatepickerProps {
  modelValue?: string;
  placeholder?: string;
  label?: string;
  helperText?: string;
  error?: string;
  disabled?: boolean;
  id?: string;
  min?: string;
  max?: string;
}

Developer tips

Common mistakes

Production usage tips

Premium examples

Advanced patterns available in Byteion Pro:

Related components

• Input
• Calendar
• Combobox