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'