Formatting
This section covers how to format DateTime objects into various string representations using Nuxt Luxon.
Output Options
Nuxt Luxon provides flexible formatting options through the OutputOptions
interface:
import type { DateTimeFormatOptions, ToISOTimeOptions, ToRelativeOptions, ToSQLOptions, Zone } from 'luxon'
interface OutputOptions {
locale?: string
format?: string | DateTimeFormatOptions | Intl.DateTimeFormatOptions
relative?: ToRelativeOptions
sql?: ToSQLOptions
iso?: ToISOTimeOptions
zone?: string | Zone
}
Format Options
format: The format to use for formatting.
- Set of Tokens: You can use a set of tokens to define the output format. Tokens represent different parts of the date and time, such as year, month, day, hour, minute, etc. See Tokens for possible values.
- Template Name: You can specify the name of a predefined template. Templates are predefined formats that can be used to quickly format dates and times. See Templates for possible values.
- DateTimeFormatOptions: Options for the DateTime format. See DateTimeFormatOptions for possible values.
locale: The locale to use for formatting. If not set, the client's locale will be used.
relative: Options for the relative format. See Relative for possible values.
sql: Options for the SQL format. See SQL for possible values.
iso: Options for the ISO format. See ISO for possible values.
Zone
The zone
option allows you to specify the timezone for the formatted output.
Examples:
UTC
America/New_York
Asia/Tokyo
local
(for the system's local zone)
For a comprehensive list of timezone identifiers, refer to the list on Wikipedia.
Locale
The locale
option determines the language and regional formatting rules to use.
Examples:
en
: English (primary language)hi
: Hindi (primary language)de-AT
: German as used in Austria (primary language with country code)zh-Hans-CN
: Chinese written in simplified characters as used in China
If not specified, the client's locale will be used by default.
Examples
Basic Formatting
const { $luxon } = useLuxon()
// Format current date with predefined templates
$luxon(new Date(), 'short') // '7/12/2024, 12:23 PM'
$luxon(new Date(), 'full') // 'July 12, 2024 at 12:23 PM UTC'
$luxon(new Date(), 'fulls') // 'July 12, 2024 at 12:23:49 PM UTC'
$luxon(new Date(), 'huge') // 'Friday, July 12, 2024 at 12:23 PM UTC'
// Format specific dates
$luxon('2024-07-12T12:23:49.000Z', 'short') // '7/12/2024, 12:23 PM'
$luxon('2024-07-12', 'date_short') // '7/12/2024'
Date-Only Formatting
const { $luxon } = useLuxon()
// Date-specific formats
$luxon('2024-07-12', 'date_full') // 'July 12, 2024'
$luxon('2024-07-12', 'date_huge') // 'Friday, July 12, 2024'
$luxon('2024-07-12', 'date_med') // 'Jul 12, 2024'
$luxon('2024-07-12', 'date_medd') // 'Fri, Jul 12, 2024'
$luxon('2024-07-12', 'date_short') // '7/12/2024'
Time-Only Formatting
const { $luxon } = useLuxon()
// Time-specific formats
$luxon('16:20:00', 'time') // '4:20 PM'
$luxon('16:20:00', 'times') // '4:20:00 PM'
$luxon('16:20:00', 'time24') // '16:20'
$luxon('16:20:00', 'time24s') // '16:20:00'
$luxon('16:20:00', 'time24longoffset') // '16:20:00 UTC'
Specialized Formats
const { $luxon } = useLuxon()
// Special formats
$luxon('2024-07-12T12:23:49.000Z', 'iso') // '2024-07-12T12:23:49.000Z'
$luxon('2024-07-12T12:23:49.000Z', 'sql') // '2024-07-12 12:23:49.000 Z'
$luxon('2024-07-12T12:23:49.000Z', 'http') // 'Fri, 12 Jul 2024 12:23:49 GMT'
$luxon('2024-07-12T12:23:49.000Z', 'rfc') // 'Fri, 12 Jul 2024 12:23:49 +0000'
// Numeric formats
$luxon('2024-07-12T12:23:49.000Z', 'millis') // 1720787029000
$luxon('2024-07-12T12:23:49.000Z', 'unix') // 1720787029
$luxon('2024-07-12T12:23:49.000Z', 'seconds') // 1720787029
// JavaScript Date object
const jsDate = $luxon('2024-07-12T12:23:49.000Z', 'jsdate') // returns Date object
Custom Format Strings
const { $luxon } = useLuxon()
// Custom format strings
$luxon(new Date(), 'yyyy-MM-dd') // '2024-07-12'
$luxon(new Date(), 'dd/MM/yyyy HH:mm:ss') // '12/07/2024 12:23:49'
$luxon(new Date(), 'ccc, d LLL yyyy') // 'Fri, 12 Jul 2024'
With Timezone and Locale Options
const { $luxon } = useLuxon()
// Format with custom timezone
$luxon('2024-07-12T12:23:49.000Z', {
format: 'full',
zone: 'America/New_York'
}) // 'July 12, 2024 at 8:23 AM EDT'
// Format with custom locale
$luxon('2024-07-12T12:23:49.000Z', {
format: 'full',
locale: 'it'
}) // '12 luglio 2024 alle ore 12:23 UTC'
// Format with both custom timezone and locale
$luxon('2024-07-12T12:23:49.000Z', {
format: 'full',
zone: 'Europe/Rome',
locale: 'it'
}) // '12 luglio 2024 alle ore 14:23 CEST'
Using with Custom Input Format
const { $luxon } = useLuxon()
// Format with custom input format
$luxon('12/07/2024', 'full', 'dd/MM/yyyy')
// 'July 12, 2024 at 12:00 AM UTC'
// Format with custom input timezone
$luxon('2024-07-12T12:23:49', { format: 'huges', zone: 'Europe/Rome' }, { zone: 'Asia/Tokyo' })
// 'Friday, July 12, 2024 at 5:23:49 AM Central European Summer Time'
Using Custom Templates
// In nuxt.config.ts
export default defineNuxtConfig({
modules: ['nuxt-luxon'],
luxon: {
templates: {
date: { format: 'dd/MM/yyyy' },
customTime: { format: 'HH:mm:ss (z)' }
}
}
})
// In your component
const { $luxon } = useLuxon()
$luxon('2024-07-12T12:23:49.000Z', 'date') // '12/07/2024'
$luxon('2024-07-12T12:23:49.000Z', 'customTime') // '12:23:49 (UTC)'
Relative Time Formatting
const { $luxon } = useLuxon()
// Format as relative time
$luxon(new Date(), 'relative') // 'just now'
$luxon(DateTime.now().minus({ days: 1 }), 'relative') // '1 day ago'
$luxon(DateTime.now().plus({ hours: 5 }), 'relative') // 'in 5 hours'
// With custom options
$luxon(DateTime.now().minus({ months: 2 }), {
format: 'relative',
relative: { unit: 'months' }
}) // '2 months ago'