Skip to main content

​
Examples

Basic time field exampleBasic time field example
NeoTimeField(
  time: selectedTime.value, // Using hooks
  onSubmitted: (value) {
    selectedTime.value = value;
  },
),

​
Properties

​
Required

​
onSubmitted
ValueChanged<TimeOfDay?>
required
Callback triggered when user completes editing (all segments filled or Enter pressed). Receives a TimeOfDay object with validated hour and minute values, or null when the field is cleared or contains invalid input.

​
Content

​
label
String?
Optional label text displayed above the time field.
​
description
String?
Optional helper text displayed below the field. Hidden when errorText is present.

​
State

​
errorText
String?
Error message displayed below the field. When present, shows error state with danger-colored border and replaces the description text.
​
isEnabled
bool
default:"true"
Controls whether the field accepts input and focus. When disabled, the field appears dimmed and prevents all interaction.
​
time
TimeOfDay?
The current time value. Use null to clear the field. The field will display the time in HH:MM format.
​
focusNode
FocusNode
Focus node for managing focus state programmatically. When not provided, the widget creates its own internal focus node.
​
onBlur
VoidCallback
Callback function called when the field loses focus. Useful for explicit blur event handling.
​
showClearButton
bool
default:"false"
Whether to show a clear button (x) that allows users to quickly clear the time field content.

​
Input Behavior

​
Value Clamping

  • Typing: Hours clamped to 0-23, minutes to 0-59
  • Arrow keys: Context-aware clamping with the same ranges
  • Validation: Automatic normalization ensures valid time values

​
Auto-Advance

  • Hour: Advances when typing ≥ 3 (e.g., “3” becomes “03” and advances)
  • Minute: Submits when 2 digits entered and hour is filled
  • Arrow keys: Move between segments or increment/decrement values (↑/↓ by 1, ←/→ between segments)
  • Tab: Standard focus navigation with Shift+Tab for reverse
  • Click: Jump to any segment and select all content
  • Enter: Submit the current time value

​
Best Practices

  • Width constraints: Wrap in SizedBox, Expanded, or ConstrainedBox to prevent layout issues
  • Time validation: Implement custom validation in onSubmitted for business rules (e.g., business hours, appointment slots)
  • Error handling: Clear errorText and update time in onSubmitted for smooth UX

​
Integration Notes

  • Automatic normalization: Invalid times are automatically corrected to valid ranges (e.g., 25:00 becomes 23:00)
Last modified on January 21, 2026