Date Time Picker

Date Time Picker

Native combined date-and-time picker field backed by @react-native-community/datetimepicker.

Distribution status

BeeUI packages and the public CLI remain unpublished. The import shape below is the stable public package boundary used by workspace/packed-consumer verification; use the repository-local Registry command only from a BeeUI checkout until publication is explicitly authorized.

Identity

• Category: Forms & selection
• Status: stable public Registry/export-map component family
• Targets: iOS · Android · Web, subject to the compatibility contract
• Source: packages/ui/src/components/date-time-picker.native.tsx

Import

import { DateTimePicker } from '@beemvp/beeui-ui';

There is no documented deep/private source import. For source ownership from a BeeUI checkout:

pnpm beeui -- add date-time-picker

Registry metadata: registry/registry.json.

Composition and public API

• Primary export: DateTimePicker

Exported types: DateTimePickerAlign, DateTimePickerCollisionPadding, DateTimePickerDirection, DateTimePickerPlacement, DateTimePickerProps, DateTimePickerValue

The generated API inventory is mechanically joined to packages/ui/src/index.ts, Registry metadata, and the component reference contract. For behavior details and defaults, use the canonical component behavior catalog rather than copying TypeScript declarations into a second hand-maintained table.

State and behavior contract

Controlled/uncontrolled props, callbacks, disabled semantics, normalization/fail-safe behavior, and mount/unmount rules are defined by the public types and the canonical behavior catalog. The executable fixtures below are the source-grounded usage examples; consumers should not infer state ownership from DOM structure or another UI library.

Provider and dependencies

• BeeUIProvider is required above this family because it participates in shared overlay/toast runtime infrastructure.
• Peer/native dependencies visible to this Registry item: @react-native-community/datetimepicker, react, react-native
• Registry dependency closure: button, calendar, core-overlay, dialog, field-context, icon-button, input, popover, segmented-control, text, theme
• Safe-area ownership remains explicit: shell surfaces touching system edges opt into SafeArea; components do not silently invent app-shell insets.
• Web consumers load the BeeUI semantic theme CSS as documented in Web onboarding.

Platform behavior

This family has platform-split source files. The bundler selects the native/Web implementation; do not infer native runtime behavior from the Web preview.

• Web: live browser/keyboard behavior is verified by Web-specific checks where applicable.
• iOS / Android: package/export/native compile evidence is not described as device-runtime proof. Consult the compatibility and native-preview guides for the exact evidence class.
• Platform-specific or experimental behavior is called out in the canonical component/compatibility docs rather than hidden behind a generic parity claim.

Accessibility

Use the Accessibility overview, RTL/localization, and Large text & zoom alongside this family. Roles/states, keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL, and reduced-motion expectations remain component-specific; BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

BeeUI components consume semantic tokens and support the current typed variant/density contracts. Use Theming and Density. className is an implementation escape hatch for source-owned/application work, not a cross-engine portability guarantee.

Executable examples

• Primary executable fixture: apps/showcase/component-gallery/date-time-picker-showcase.tsx

Open the matching Web runtime in Showcase. The Showcase link demonstrates Web behavior; use the native-preview guide for real simulator/emulator/device paths.

Live Web preview

This frame loads the real BeeUI Web Showcase on demand; it is not a second docs-only implementation. It proves browser behavior only. Use native preview for iOS/Android simulator, emulator or device paths.

Composition anatomy

• Family root / primary export: DateTimePicker
  • Exported type surface:
    • DateTimePickerAlign
    • DateTimePickerCollisionPadding
    • DateTimePickerDirection
    • DateTimePickerPlacement
    • DateTimePickerProps
    • DateTimePickerValue

The tree above is ordinary document structure so it remains readable with keyboard and assistive technology; it is derived from the real public export family rather than a canvas-only diagram.

Verified example source

The following is the exact typechecked runtime Showcase fixture selected for this live preview: apps/showcase/component-gallery/date-time-picker-showcase.tsx. Runtime gallery/pattern sources are preferred over test harnesses, and the displayed source and executable source are the same file; there is no separately maintained demo snippet.

import {
  Card,
  DateTimePicker,
  Field,
  Section,
  Text,
  VStack,
  type DateTimePickerValue,
} from '@beemvp/beeui-ui';
import * as React from 'react';

// BeeUI issue #174 (R4F.4, ADR-008 "DateTimePicker" contract). A minimal, representative
// gallery fixture for Playwright browser-interaction evidence: keyboard grid
// navigation inside the Popover-hosted Calendar, hour/minute digit-entry focus, AM/PM
// toggling, Escape dismissal, and focus restoration. Deterministic behavior (selection,
// clearing, bounds/disabled dates, Field error semantics, controlled-state edge cases)
// already has Jest coverage in
// `apps/showcase/__tests__/issue-174-date-time-picker-web.test.tsx`; this fixture
// exists for what only a real browser can prove.

const MIN_DATE = { day: 5, month: 1, year: 2026 };
const MAX_DATE = { day: 25, month: 1, year: 2026 };

function isWeekend(date: { day: number; month: number; year: number }): boolean {
  const dayOfWeek = new Date(Date.UTC(date.year, date.month - 1, date.day)).getUTCDay();
  return dayOfWeek === 0 || dayOfWeek === 6;
}

function formatValueState(value: DateTimePickerValue | null): string {
  if (!value) return 'null';
  const { date, time } = value;
  return `${date.year}-${date.month}-${date.day} ${String(time.hour).padStart(2, '0')}:${String(
    time.minute,
  ).padStart(2, '0')}`;
}

export function DateTimePickerShowcase() {
  // Seeded to a January 2026 weekday (not `null`) so the Calendar's initial visible
  // month is deterministic and the time fields have a stable starting value.
  const [controlledValue, setControlledValue] = React.useState<DateTimePickerValue | null>({
    date: { day: 15, month: 1, year: 2026 },
    time: { hour: 13, minute: 30 },
  });
  const [boundedValue, setBoundedValue] = React.useState<DateTimePickerValue | null>({
    date: { day: 15, month: 1, year: 2026 },
    time: { hour: 9, minute: 0 },
  });
  const [fieldValue, setFieldValue] = React.useState<DateTimePickerValue | null>(null);

  return (
    <VStack gap="lg">
      <Card className="gap-5" variant="raised">
        <Section
          description="Controlled selected date+time, formatted display, and an explicit clear affordance."
          title="Controlled DateTimePicker"
        >
          <VStack gap="xs">
            <DateTimePicker
              onValueChange={setControlledValue}
              testID="date-time-picker-showcase-controlled"
              value={controlledValue}
            />
            <Text testID="date-time-picker-showcase-controlled-state" tone="muted" variant="caption">
              {`value: ${formatValueState(controlledValue)}`}
            </Text>
          </VStack>
        </Section>
      </Card>

      <Card className="gap-5">
        <Section
          description="min/max bounds and a weekend isDateDisabled predicate block date selection in the Calendar grid; 24h time entry."
          title="Bounded / disabled dates, 24h time"
        >
          <DateTimePicker
            hour12={false}
            isDateDisabled={isWeekend}
            max={MAX_DATE}
            min={MIN_DATE}
            onValueChange={setBoundedValue}
            testID="date-time-picker-showcase-bounded"
            value={boundedValue}
          />
        </Section>
      </Card>

      <Card className="gap-5">
        <Section description="Field-integrated trigger derives label/required/error." title="Field validation">
          <Field
            error={fieldValue ? undefined : 'Appointment time is required'}
            invalid={!fieldValue}
            label="Appointment"
            required
          >
            <DateTimePicker
              onValueChange={setFieldValue}
              testID="date-time-picker-showcase-field"
              value={fieldValue}
            />
          </Field>
        </Section>
      </Card>
    </VStack>
  );
}

Use the code block’s copy affordance to copy the exact fixture. For a smaller app-specific example, start from the public imports shown above and keep only the state your screen owns.

Limitations

No component-specific limitation is curated here. Check Compatibility and the linked behavior contract for target-specific constraints.

Implementation note: Platform-split module; segmented date/time entry on native.

Related

• All component reference pages
• Production patterns
• Showcase
• CLI & source ownership
• Source