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.
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 blurWhy 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.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | - | 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. |
| label | React.ReactNode | - | Label text displayed above the picker |
| value | string | 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. |
| error | boolean | false | If 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). |
| helperText | string | - | 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). |
| disabled | boolean | false | If true, the picker is disabled |
| rules | ValidationRules | - | 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.