DateTimePicker | Dashforge-UI
DocsStarter Kits
v0.1.0-alpha

DateTimePicker

A flexible date and time input component built on native HTML inputs. Supports date-only, time-only, and datetime modes with ISO 8601 UTC storage. Integrates seamlessly with DashForm for validation, error handling, and reactive visibility.

Quick Start

READY

import { DashForm } from '@dashforge/forms';
import { DateTimePicker } from '@dashforge/ui';

function AppointmentForm() {
  const handleSubmit = (data) => {
    console.log('Appointment:', data.appointmentTime);
    // Value is ISO 8601 UTC string: "2024-03-28T14:30:00.000Z"
  };

  return (
    <DashForm onSubmit={handleSubmit}>
      <DateTimePicker
        name="appointmentTime"
        label="Appointment Date & Time"
        mode="datetime"
        rules={{ required: 'Please select a date and time' }}
      />
      <button type="submit">Schedule</button>
    </DashForm>
  );
}

Examples

Common usage patterns and configurations

DateTime Mode

Combined date and time selection for appointments

<DateTimePicker 
  label="Appointment" 
  name="appointment" 
  mode="datetime"
/>
Date Only

Select dates for deadlines and milestones

<DateTimePicker 
  label="Deadline" 
  name="deadline" 
  mode="date"
/>
Time Only

Choose time slots without date selection

<DateTimePicker 
  label="Meeting Time" 
  name="meetingTime" 
  mode="time"
/>
With Helper Text

Guide users with contextual instructions

Select when you want to be reminded

<DateTimePicker 
  label="Reminder" 
  name="reminder"
  mode="datetime"
  helperText="Select when you want to be reminded"
/>
Error State

Validation feedback for required datetime fields

Event start time is required

<DateTimePicker
  label="Event Start"
  name="eventStart"
  mode="datetime"
  error
  helperText="Event start time is required"
/>
Disabled

Prevent interaction when datetime is locked

<DateTimePicker
  label="Publish Date"
  name="publishDate"
  mode="datetime"
  disabled
/>

Dashforge Capabilities

What makes DateTimePicker powerful in the Dashforge ecosystem

DateTimePicker is designed for progressive adoption. Use it as a simple controlled component, integrate it with React Hook Form, or leverage Dashforge-native reactive capabilities. Choose the level that fits your team's workflow.

Controlled

Available Now

DateTimePicker works as a standard React controlled component with ISO 8601 UTC storage. No proprietary lock-in required.

ISO 8601 UTC value format

Standard onChange callback pattern

No external dependencies required

<DateTimePicker
  value={startTime}
  onChange={(iso) => setStartTime(iso)}
  label="Event start time"
  mode="datetime"
/>

React Hook Form Ready

Integration-Friendly

Designed to integrate with React Hook Form workflows through DashForm. Supports validation, error gating, and touch tracking.

Works through DashForm bridge

Validation rules supported

Error gating on touch/submit

<DashForm>
  <DateTimePicker 
    name="appointment"
    label="Appointment time"
    mode="datetime"
    rules={{
      required: 'Please select a time'
    }}
  />
</DashForm>

Reactive Visibility

Available Now

DateTimePicker can participate in engine-driven visibility rules through visibleWhen. Use it when date/time input depends on other form state.

Conditional rendering via visibleWhen

Engine evaluates the predicate

Useful for dependent scheduling fields

<DateTimePicker
  name="reminderTime"
  label="Reminder time"
  mode="datetime"
  visibleWhen={(engine) => 
    engine.getNode('enableReminder')?.value === true
  }
/>

Access Control (RBAC)

Control field visibility and interaction based on user permissions. Fields can be hidden, disabled, or readonly when users lack access.

Hide when unauthorized

<DateTimePicker
  name="publishedAt"
  label="Published At"
  access={{
    resource: 'article.publishedAt',
    action: 'read',
    onUnauthorized: 'hide',
  }}
/>

Disable when cannot edit

<DateTimePicker
  name="startAt"
  label="Start Date"
  access={{
    resource: 'event.startAt',
    action: 'update',
    onUnauthorized: 'disable',
  }}
/>

Readonly for view-only

<DateTimePicker
  name="expiresAt"
  label="Expiration Date"
  access={{
    resource: 'subscription.expiresAt',
    action: 'update',
    onUnauthorized: 'readonly',
  }}
/>

Combined with visibleWhen

<DateTimePicker
  name="reminderAt"
  label="Reminder Date"
  mode="datetime"
  visibleWhen={(e) =>
    e.getValue('enableReminders') === true
  }
  access={{
    resource: 'task.reminderAt',
    action: 'read',
    onUnauthorized: 'hide',
  }}
/>

Note: When combining visibleWhen with RBAC, both conditions must be satisfied. The field shows only if UI logic returns true AND the user has required permissions.


Form Integration Scenarios

Real-world usage in forms and applications

DateTimePicker works in real form contexts, not just isolated demos. Try these live scenarios to experience DashForm integration and reactive visibility—both fully implemented and production-ready.

React Hook Form Integration

Try it: Select dates/times and submit the schedule

DateTimePicker integrates seamlessly with React Hook Form through DashForm. Components self-register, values sync automatically in ISO 8601 UTC format, and validation works out of the box. Try selecting dates and times to see validation in action (appointment and deadline are required). Submit the form to see the complete state.

Live Preview

Schedule Appointment

Select your preferred meeting time

import { DashForm } from '@dashforge/forms';
import { DateTimePicker } from '@dashforge/ui';

function AppointmentScheduler() {
  const handleSubmit = (data: FormData) => {
    console.log('Scheduled:', data);
    // All values are ISO 8601 UTC strings or null
  };

  return (
    <DashForm
      defaultValues={{ 
        appointmentDate: null,
        deadlineDate: null,
        meetingTime: null
      }}
      onSubmit={handleSubmit}
      mode="onBlur"
    >
      <DateTimePicker
        name="appointmentDate"
        label="Appointment date & time"
        mode="datetime"
        rules={{
          required: 'Please select an appointment time'
        }}
      />
      <DateTimePicker
        name="deadlineDate"
        label="Project deadline"
        mode="date"
        rules={{
          required: 'Please select a deadline'
        }}
      />
      <DateTimePicker
        name="meetingTime"
        label="Daily meeting time"
        mode="time"
        helperText="Select your preferred meeting time"
      />
      <button type="submit">Schedule</button>
    </DashForm>
  );
}

// DateTimePicker automatically:
// - Registers with React Hook Form
// - Syncs value from form state (ISO 8601 UTC)
// - Returns ISO strings on submit
// - Shows errors only after touched OR submit
// - Tracks touched state on blur

Why it matters

Gradual adoption: Drop DateTimePicker into existing form architectures without rewriting state management. Perfect for scheduling systems, booking forms, deadline trackers, and any date/time input.

Reactive Conditional Visibility

Try it: Select an event type and enable reminder to see pickers appear

DateTimePicker supports conditional rendering through the visibleWhen prop. Fields render based on engine state—components query field values and make rendering decisions. Select an event type to see the date picker appear. Enable the reminder switch to reveal the reminder date/time picker instantly without manual state orchestration. This is part of Dashforge Reactive V2 architecture.

Live Preview

Create Event

import { DashForm } from '@dashforge/forms';
import { DateTimePicker, Select, Switch } from '@dashforge/ui';

function EventCreator() {
  return (
    <DashForm 
      defaultValues={{ 
        eventType: '',
        enableReminder: false,
        eventDate: null,
        reminderTime: null
      }}
    >
      <Select
        name="eventType"
        label="Event type"
        options={[
          { label: 'Meeting', value: 'meeting' },
          { label: 'Deadline', value: 'deadline' },
          { label: 'Reminder', value: 'reminder' }
        ]}
      />

      {/* Event date: appears when event type is selected */}
      <DateTimePicker
        name="eventDate"
        label="Event date"
        mode="date"
        visibleWhen={(engine) => {
          const eventType = engine.getNode('eventType')?.value;
          return eventType !== '' && eventType !== null;
        }}
      />

      <Switch
        name="enableReminder"
        label="Enable reminder"
      />

      {/* Reminder time: appears only when enabled */}
      <DateTimePicker
        name="reminderTime"
        label="Reminder date & time"
        mode="datetime"
        visibleWhen={(engine) => {
          const enabled = engine.getNode('enableReminder')?.value;
          return enabled === true;
        }}
      />
    </DashForm>
  );
}

// The Engine API provides:
// - getNode(name): Access any field's state
// - Component re-renders on dependency changes
// - Component makes rendering decision (engine provides state)

Why it matters

Build adaptive scheduling forms where date/time pickers respond to user selections. The component handles conditional rendering—you define the predicate. Perfect for dynamic event forms, conditional deadlines, and context-dependent scheduling.


API Reference

Complete props documentation

Storage Format: DateTimePicker stores values as ISO 8601 UTC strings (e.g., "2024-03-28T14:30:00.000Z") or null. The component automatically converts between ISO format and native input format. Explicit vs Auto-Bound Props: When inside DashForm, DateTimePicker receives value, error, helperText, onChange, and onBlur automatically through field binding. Explicit props always take precedence over form-provided values.

PropTypeDefaultDescription
namestring-Field name for form integration (required)
mode"date" | "time" | "datetime""datetime"Picker mode: "date" for date-only, "time" for time-only, "datetime" for date and time combined. Determines the native input type used.
labelReact.ReactNode-Label text displayed above the picker
valuestring | null-Controlled value in ISO 8601 UTC format. Example: "2024-03-28T14:30:00.000Z". Component converts between ISO and native input format automatically.
onChange(value: string | null) => void-Callback fired when the value changes. Receives ISO 8601 UTC string or null. Simplified from standard onChange—no event wrapper.
errorbooleanfalseIf true, displays error state. Explicit error prop overrides form-provided error state. When inside DashForm without explicit prop, error is gated (shows only when touched OR submitted).
helperTextstring-Helper text displayed below picker. Explicit helperText prop overrides form-provided validation error message. When inside DashForm, validation errors display as helperText (gated by touched/submitted state).
disabledbooleanfalseIf true, the picker is disabled
rulesValidationRules-Validation rules for DashForm integration. Format follows React Hook Form rules contract (required, validate, etc.). Only used when inside DashForm—ignored in standalone mode.
visibleWhen(engine: Engine) => boolean-Component-level conditional rendering predicate. Receives engine instance with access to all field state via getNode(name). When false, component renders null. Re-evaluates on dependency changes. Only works inside DashForm (requires engine).

Under the hood

How DateTimePicker works internally

Form integration

Automatically binds to form state inside DashForm. No manual wiring required. Works standalone with explicit value/onChange props. Values are ISO 8601 UTC strings (e.g., "2024-03-28T14:30:00.000Z").

Behavior model

Three modes: "date", "time", or "datetime" (default). Built on native HTML inputs for zero dependencies. Errors appear only after blur or submit. Supports visibleWhen for conditional rendering via Reactive V2.

Architecture

Built on native HTML date/time inputs, not MUI X Date Pickers. Browser appearance varies, but data handling is consistent. Purpose-built for appointments, deadlines, reminders, and any timestamp input.


On This Page