DateTime API

Per-option reference for the :date_time field. For tasks and examples, see the DateTime guide.

Options are passed to a field declaration in an Avo resource, such as app/avo/resources/event.rb:

field :starts_at, as: :date_time

Shared options, including link_to_record, are covered in common field options.

Display formatting

-> format

The format used on Index and Show pages. Textual date parts use the page's locale.

field :starts_at, as: :date_time, format: "dd LLL yyyy HH:mm"

• Type: String
• Default: "yyyy-LL-dd TT"
• Values: Luxon formatting tokens.

-> picker_format

The visible input format on New and Edit pages. It does not change the submitted timestamp format.

field :starts_at, as: :date_time, picker_format: "d M Y H:i"

• Type: String
• Default: "Y-m-d H:i:S"
• Values: flatpickr formatting tokens.

Different token systems

format uses Luxon tokens; picker_format uses flatpickr tokens. They are not interchangeable.

Timezone conversion

-> relative

Controls whether the timestamp is converted from UTC to the display timezone. This is timezone conversion, not relative wording such as "two hours ago".

field :starts_at, as: :date_time, relative: false

Value	Behavior
true	Displays and edits in the configured timezone, or the browser's timezone when none is configured; picker changes are converted back to UTC.
false	Displays UTC on Index and Show; the picker retains the UTC clock time and submits it as UTC without applying a timezone offset.

• Type: Boolean
• Default: true

-> timezone

The display timezone when relative is true. A block can return a different timezone for each record.

field :starts_at, as: :date_time, timezone: -> { record.timezone }

• Type: String or Proc / Lambda returning a timezone identifier or nil
• Default: nil (uses the browser's timezone)
• Values: Timezone identifiers understood by Luxon, such as "America/Los_Angeles" or "UTC". See also Rails' timezone documentation.
• Context: Blocks run in Avo::ExecutionContext with record, resource, and view available.

INFO

With relative: false, the configured timezone does not shift the displayed clock time. Avo normalizes "UTC" to "Etc/UTC" on form views for compatibility with Luxon.

Picker controls

-> time_24hr

Controls the picker's hour selection. Index and Show formatting is controlled separately by format.

field :starts_at, as: :date_time, time_24hr: true

Value	Behavior
false	Uses AM/PM selection.
true	Uses 24-hour selection.

• Type: Boolean
• Default: false

-> first_day_of_week

The first weekday in the picker calendar, forwarded to flatpickr's locale.firstDayOfWeek. See flatpickr localization.

field :starts_at, as: :date_time, first_day_of_week: 0

Value	Weekday
0	Sunday
1	Monday
2	Tuesday
3	Wednesday
4	Thursday
5	Friday
6	Saturday

• Type: Integer
• Default: 1
• Validation: Avo does not validate the weekday range; flatpickr expects 0 through 6.

-> disable_mobile

Disables flatpickr's native mobile picker fallback. See flatpickr mobile support.

field :starts_at, as: :date_time, disable_mobile: true

Value	Behavior
false	Allows a native mobile picker where flatpickr supports it.
true	Uses flatpickr on mobile too.

• Type: Boolean
• Default: false

-> picker_options

Additional flatpickr options, applied on New and Edit pages. Avo fills locale.weekdays and locale.months from the app locale and merges a supplied locale over them.

field :starts_at, as: :date_time, picker_options: { minDate: "today" }

• Type: Hash
• Default: {}
• Values: flatpickr options.
• Validation: These settings constrain the picker, not server-side model validation.

Avo-controlled settings

Avo sets altFormat, disableMobile, locale.firstDayOfWeek, enableTime, enableSeconds, noCalendar, and dateFormat after merging picker_options. Avo also supplies defaultDate when the field has a value. Those settings cannot be overridden through this Hash. Other options, including callbacks, are forwarded to flatpickr and can replace Avo's defaults.