# Luxon 2 Plugin

> FullCalendar v5 documentation, for an old release. Web version: https://legacy.fullcalendar.io/v5/luxon2
>
> Latest version (v7): https://fullcalendar.io/docs/format-luxon3.md

[Luxon](https://moment.github.io/luxon/index.html) is a JavaScript date library that cleverly leverages the browser's native APIs for many things such as time zones, locales, and formatting. However, it requires **IE11 and above**, and if you want to use named time zones, **it does not support IE at all**, only Microsoft Edge. If these browser requirements are okay for your project, then all is good!

The FullCalendar plugin provides you the following functionality:

- Lets you use Luxon [formatting strings](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) for all date-formatting settings
- Lets you convert native [Date objects](https://legacy.fullcalendar.io/v5/date-object.md) emitted from the API into [Luxon DateTime objects](https://moment.github.io/luxon/api-docs/index.html#datetime) that match the calendar's time zone and locale
- Lets you convert [Duration objects](https://legacy.fullcalendar.io/v5/duration-object.md) emitted from the API into [Luxon Durations objects](https://moment.github.io/luxon/api-docs/index.html#duration)
- Provides you a named time-zone implementation for the [timeZone](https://legacy.fullcalendar.io/v5/timeZone.md) setting


## Usage with NPM

First, install the `@fullcalendar/luxon2` package along with any other packages you plan to use:

```
npm install --save @fullcalendar/luxon2 @fullcalendar/core @fullcalendar/daygrid
```

Then, create a new calendar and pass in the plugins:

```js
import { Calendar } from '@fullcalendar/core'
import luxon2Plugin from '@fullcalendar/luxon2'
import dayGridPlugin from '@fullcalendar/daygrid'

let calendar = document.getElementById('calendar')
let calendar = new Calendar(calendarEl, {
  plugins: [ luxon2Plugin, dayGridPlugin ],
  titleFormat: 'LLLL d, yyyy' // you can now use Luxon format strings!
})

calendar.render()
```


## Usage with Script Tags

You can also configure the Luxon plugin with [script tags](https://legacy.fullcalendar.io/v5/initialize-globals.md). This example leverages CDN links:

```html
<!-- luxon lib -->
<script src='https://cdn.jsdelivr.net/npm/luxon@2.3.0/build/global/luxon.min.js'></script>

<!-- fullcalendar bundle -->
<script src='https://cdn.jsdelivr.net/npm/fullcalendar@5.11.5/main.min.js'></script>

<!-- the luxon-to-fullcalendar connector. must go AFTER the luxon lib -->
<script src='https://cdn.jsdelivr.net/npm/@fullcalendar/luxon2@5.11.5/main.global.min.js'></script>

<script>
  var calendar = document.getElementById('calendar')
  var calendar = new FullCalendar.Calendar(calendarEl, {
    titleFormat: 'LLLL d, yyyy' // you can now use Luxon format strings!
  })

  calendar.render()
</script>
```


## Formatting

The plugin allows you to specify [luxon formatting strings](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) wherever a [date formatting input](https://legacy.fullcalendar.io/v5/date-formatting.md) is expected:

```js
var calendar = new FullCalendar.Calendar(calendarEl, {
  titleFormat: 'LLLL d, yyyy' // you can now use Luxon format strings!
})
```

If you want to format a date *range*, you can group related date parts with curly brackets:

```js
var calendar = new FullCalendar.Calendar(calendarEl, {
  titleFormat: '{LLLL {d}}, yyyy'
  // could produce "January 5 - 7, 2018"
  // could produce "January 5 - February 31, 2018"
  // could produce "January 5, 2018 - June 9, 2019"
});
```


## Luxon Objects

Using the provided utility methods, you can convert dates and durations supplied by FullCalendar's API into Luxon objects and durations:

```js
import { Calendar } from '@fullcalendar/core';
import { toLuxonDateTime, toLuxonDuration } from '@fullcalendar/luxon2';
...
let calendar = new Calendar(calendarEl, {

  dateClick: function(arg) {
    let dt = toLuxonDateTime(arg.date, calendar); // calendar is required
    console.log('clicked on ' + dt.toISO());
  },

  eventDrop: function(arg) {
    let dur = toLuxonDuration(arg.delta, calendar); // calendar is required
    console.log('event moved ' + dur.toISO());
  }
});
...
```

When using script tags, these utility functions are available as `FullCalendarLuxon2.toLuxonDateTime` and `FullCalendarLuxon2.toLuxonDuration`.