Date Time Picker

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

Distribution status

BeeUI 0.86.2-rc.3 is public on npm under the opt-in next dist-tag (observed 2026-09-25T06:25:18.371Z). latest currently resolves to 0.86.2-rc.3 and lags next until the owner moves it for all four packages. See Start for the full install commands. The import shape below works against the published package; the repository-local Registry command remains available as a no-registry-required alternative from a BeeUI checkout. Pin @0.86.2-rc.3 instead of @next for an immutable version in CI.

Identity

• Category: Forms & selection
• Status: stable public Registry/export-map component family
• Targets: iOS · Android · Web, subject to the compatibility contract
• Prerequisites: @beemvp/beeui-ui installed (or this component’s source copied via the Registry CLI below) and, on Web, the BeeUI Tailwind/Uniwind theme CSS loaded — see Start for full platform setup.
• 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 (used throughout this page) is BeeUI’s source-ownership manifest — registry/registry.json — that the pnpm beeui/@beemvp/beeui-cli CLI reads to copy a component’s real source into your app and rewrite its internal imports; it is not an npm package index. This component’s own Registry entry: registry/registry.json.

Composition and public API

• Primary export: DateTimePicker
  • Also routed here, outside the Registry family:
    • date-time-picker
  • Package export subpath: @beemvp/beeui-ui/date-time-picker

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. Each type’s field table below is parsed directly from that source, not a second hand-maintained copy; for the fuller behavior narrative see the canonical component behavior catalog.

State and behavior contract

Controlled value/onValueChange ({ date, time } | null) field combining date and time entry through the native system pickers; disabled blocks opening either sub-picker. A wrapping Field’s required state no longer injects an English word into the trigger’s accessible name — pass the field’s own localized-required prop to append copy instead.

Props

DateTimePickerProps

Prop	Type	Default	Description
accessibilityLabel	string	—	Accessible name for the trigger. Falls back to the enclosing Field’s label.
align	DateTimePickerAlign	'start'	Web-only: Popover content alignment relative to the trigger. Ignored on native.
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
clearAccessibilityLabel	string	'Clear date and time'	Accessible label for the clear button shown when clearable and a value is selected. Defaults to 'Clear date and time'.
clearable	boolean	true	Shows a clear affordance when a value is selected. Defaults to true.
closeOnOutsidePress	boolean	true	Web-only: dismiss the Popover on an outside press. Ignored on native.
collisionPadding	DateTimePickerCollisionPadding	8	Web-only: Popover collision padding. Ignored on native.
defaultOpen	boolean	—	Uncontrolled initial open state. Ignored once open is controlled.
direction	DateTimePickerDirection	—	Web-only: logical direction for the Popover/Calendar/time content. Ignored on native.
disabled	boolean	—	Disables the trigger, so it cannot open the picker. Combined with the enclosing Field’s own disabled.
flip	boolean	true	Web-only: flips Popover placement to stay in the viewport. Ignored on native.
formatValue	(value: DateTimePickerValue, locale: string) => string	—	Overrides the default Intl-based formatted display.
hourAccessibilityLabel	string	'Hour'	Accessible name for the Web hour digit field. Defaults to 'Hour'.
hour12	boolean	—	Explicit-only 12/24h display override. Defaults to the resolved locale’s Intl.DateTimeFormat(locale, { hour: 'numeric' }).resolvedOptions().hour12 (ADR-008).
invalid	boolean	—	Marks the trigger as invalid for styling and accessibility. Combined with the enclosing Field’s own invalid.
isDateDisabled	(date: CalendarDate) => boolean	—	Marks individual dates as disabled in the Calendar grid, without disabling the trigger itself.
locale	string	—	Explicit-only (ADR-008) — no ambient device/browser locale auto-detection. Defaults to 'en-US'.
max	CalendarDate	—	Latest selectable date (inclusive), forwarded to the Calendar; later dates render disabled.
min	CalendarDate	—	Earliest selectable date (inclusive), forwarded to the Calendar; earlier dates render disabled.
minuteAccessibilityLabel	string	'Minute'	Accessible name for the Web minute digit field. Defaults to 'Minute'.
nextMonthAccessibilityLabel	string	'Next month'	Accessible label for the Calendar’s “next month” button. Defaults to 'Next month'.
onOpenChange	(open: boolean) => void	—	Controlled/uncontrolled open state — BeeUI owns Web presentation (Popover).
onValueChange	(value: DateTimePickerValue | null) => void	—	null signals an explicit clear (see clearable).
open	boolean	—	Controls whether the picker (Web Popover, native system picker) is open. Requires onOpenChange; otherwise falls back to internal open state with a dev-mode warning.
periodAccessibilityLabel	string	'AM or PM'	Accessible name for the Web AM/PM control. Defaults to 'AM or PM'.
placeholder	string	—	Text shown on the trigger when no value is selected. Defaults to 'Select a date and time'.
placement	DateTimePickerPlacement	'bottom'	Web-only: Popover placement relative to the trigger. Ignored on native.
previousMonthAccessibilityLabel	string	'Previous month'	Accessible label for the Calendar’s “previous month” button. Defaults to 'Previous month'.
readOnly	boolean	false	Keeps the trigger focusable/announced but blocks opening and clearing.
shift	boolean	true	Web-only: Popover collision-shift. Ignored on native.
sideOffset	number	8	Web-only: Popover offset from the trigger. Ignored on native.
style	StyleProp<ViewStyle>	—	Forwarded to the trigger’s root View.
testID	string	—	Test identifier. Forwarded to the native testID and, on Web, emitted as data-testid.
value (required)	DateTimePickerValue | null	—	Controlled selected date+time (ADR-008) — single-date selection only for 1.0.
weekStartsOn	CalendarWeekStartsOn	—	Which day starts each week row in the Calendar. Defaults to the convention for locale when omitted.

Related exported types:

• DateTimePickerAlign — alias of AnchoredOverlayAlign.
• DateTimePickerCollisionPadding — alias of AnchoredOverlayCollisionPadding.
• DateTimePickerDirection — alias of AnchoredOverlayDirection.
• DateTimePickerPlacement — alias of AnchoredOverlayPlacement.
• DateTimePickerValue — alias of { date: CalendarDate; time: ClockTime; }.

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
• On Web this family renders from date-time-picker.web.tsx, which does not import @react-native-community/datetimepicker: that peer serves the native implementation.
• 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 is split by platform and renders from date-time-picker.native.tsx (iOS and Android), date-time-picker.web.tsx (Web). Where the two shapes differ, the difference is listed under the affected type above rather than summarised here.

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

Evidence classes are not equal and this page does not blur them: Web behavior is exercised in a real browser, while iOS and Android carry package/export and native-compile evidence, which is not device-runtime proof. The compatibility contract records which class each claim rests on.

Accessibility

• Roles this family assigns: button (iOS and Android) — set in date-time-picker.native.tsx by the components themselves, not by the caller.
• Accessibility states and properties it sets: accessibilityHint, accessibilityLabel, accessibilityLabelledBy, disabled, expanded (Web), hidden — read from date-time-picker.native.tsx, date-time-picker.web.tsx, date-time-picker-shared.tsx.

Keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL and reduced-motion expectations are not derived here — see Accessibility overview, Keyboard & focus, RTL/localization and Large text & zoom. BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

• Style axes: not enumerated here: align, collisionPadding, direction, placement are typed by an alias this page does not resolve to values.
• Class-name surfaces: className.

Colors, spacing and typography come from semantic tokens rather than from values written here — see Theming and Density. A className is an escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Executable examples

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

Addressable examples

Each link below opens the Showcase at that exact example, not at the top of the gallery:

• basic — smallest meaningful complete usage

The Showcase links demonstrate 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

locale affects the embedded Calendar’s weekday/month grid, Intl-based date/time formatting, and — when the caller omits placeholder — the combined trigger’s default placeholder text and the picker footer’s “Done” button label, both drawn from a small built-in dictionary (en-US/vi-VN today) that falls back to the English copy for any other locale (Done has no caller-facing override prop at all; it always follows locale). It does not translate the month-navigation accessible labels or the hour/minute/period/clear accessibility labels, each a separate string prop with a hardcoded English default. A localized app must pass those explicitly alongside locale.

• Passing open without onOpenChange leaves the value read-only: the component renders what you passed and can never change it. It warns in development builds rather than failing silently in production.
• Requires @react-native-community/datetimepicker to be installed by the consuming app. It is an optional peer of @beemvp/beeui-ui, so nothing installs it for you, and a target that never renders this family does not need it.

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

Related

• All components
• Production patterns
• Showcase
• CLI & source ownership
• Source