use_intl_datetime_format

Usage

Dates are passed in as chrono::DateTime (just like in use_calendar).

In basic use without specifying a locale, a formatted string in the default locale and with default options is returned.

use leptos::prelude::*;
use leptos_use_intl_datetime_format::{use_intl_datetime_format, UseIntlDateTimeFormatOptions};
use chrono::{TimeZone, Utc};

#[component]
fn Demo() -> impl IntoView {
let (date, set_date) = signal(Utc.with_ymd_and_hms(2020, 12, 20, 3, 23, 16).unwrap());

let date_time_format = use_intl_datetime_format(UseIntlDateTimeFormatOptions::default());

let formatted = date_time_format.format(date); // "12/20/2020" if in US English locale

view! { }
}

Using locales

In order to get the format of the language used in the user interface of your application, make sure to specify that language (and possibly some fallback languages) using the locales argument:

use leptos::prelude::*;
use leptos_use_intl_datetime_format::{use_intl_datetime_format, UseIntlDateTimeFormatOptions};
use chrono::{TimeZone, Utc};

#[component]
fn Demo() -> impl IntoView {
let date = Utc.with_ymd_and_hms(2012, 12, 20, 3, 0, 0).unwrap();

// British English uses day-month-year order and 24-hour time without AM/PM
let date_time_format = use_intl_datetime_format(
    UseIntlDateTimeFormatOptions::default().locale("en-GB"),
);
let formatted = date_time_format.format(date); // 20/12/2012

// Korean uses year-month-day order
let date_time_format = use_intl_datetime_format(
    UseIntlDateTimeFormatOptions::default().locale("ko-KR"),
);
let formatted = date_time_format.format(date); // 2012. 12. 20.

// Arabic in most Arabic speaking countries uses real Arabic digits
let date_time_format = use_intl_datetime_format(
    UseIntlDateTimeFormatOptions::default().locale("ar-EG"),
);
let formatted = date_time_format.format(date); // ٢٠‏/١٢‏/٢٠١٢

// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
let date_time_format = use_intl_datetime_format(
    UseIntlDateTimeFormatOptions::default()
        .locales(vec!["ban".to_string(), "id".to_string()]),
);
let formatted = date_time_format.format(date); // 20/12/2012

view! { }
}

Using options

The results can be customized in multiple ways.

use leptos::prelude::*;
use leptos_use_intl_datetime_format::{use_intl_datetime_format, UseIntlDateTimeFormatOptions, WeekdayFormat, EraFormat, YearFormat, MonthFormat, DayFormat, TimeNumericFormat, TimeZoneNameFormat};
use chrono::{TimeZone, Utc};

#[component]
fn Demo() -> impl IntoView {
let date = Utc.with_ymd_and_hms(2012, 12, 20, 3, 0, 0).unwrap();

// request a weekday along with a long date
let date_time_format = use_intl_datetime_format(
    UseIntlDateTimeFormatOptions::default()
        .locale("en-US")
        .weekday(WeekdayFormat::Long)
        .year(YearFormat::Numeric)
        .month(MonthFormat::Long)
        .day(DayFormat::Numeric),
);
let formatted = date_time_format.format(date); // "Thursday, December 20, 2012"

// an application may want to use UTC and make that visible
let date_time_format = use_intl_datetime_format(
    UseIntlDateTimeFormatOptions::default()
        .locale("en-US")
        .hour(TimeNumericFormat::Numeric)
        .minute(TimeNumericFormat::TwoDigit)
        .second(TimeNumericFormat::TwoDigit)
        .time_zone("UTC")
        .time_zone_name(TimeZoneNameFormat::Short),
);
let formatted = date_time_format.format(date); // "3:00:00 AM UTC"

view! { }
}

Instead of specifying the individual date and time components you can use the UseIntlDateTimeFormatOptions::date_style and UseIntlDateTimeFormatOptions::time_style shortcuts.

use leptos::prelude::*;
use leptos_use_intl_datetime_format::{use_intl_datetime_format, UseIntlDateTimeFormatOptions, DateTimeStyle};
use chrono::{TimeZone, Utc};

#[component]
fn Demo() -> impl IntoView {
let date = Utc.with_ymd_and_hms(2012, 12, 20, 3, 0, 0).unwrap();

let date_time_format = use_intl_datetime_format(
    UseIntlDateTimeFormatOptions::default()
        .locale("en-GB")
        .date_style(DateTimeStyle::Full)
        .time_style(DateTimeStyle::Long)
        .time_zone("UTC"),
);
let formatted = date_time_format.format(date); // "Thursday 20 December 2012 at 03:00:00 UTC"

view! { }
}

Note that date_style and time_style cannot be mixed with the individual date-time component options (like weekday, year, hour, …). Doing so makes Intl.DateTimeFormat throw a RangeError which results in an empty string being returned.

For an exhaustive list of options see UseIntlDateTimeFormatOptions.

Formatting ranges

Apart from the format method, the format_range method can be used to format a range of dates. Please see UseIntlDateTimeFormatReturn::format_range for details.

Server-Side Rendering

Make sure you follow the instructions in Server-Side Rendering.

Since Intl.DateTimeFormat is a JavaScript API it is not available on the server. That’s why it falls back to a simple call to format!() on the server, which is not locale-aware.

Installation

cargo add leptos-use-intl-datetime-format

Options

`UseIntlDateTimeFormatOptions`

Every option is set with a builder method of the same name, e.g. UseIntlDateTimeFormatOptions::default().locales(...). See also the API docs.

`locales`

Type: Vec<String>

A vec of strings, each with a BCP 47 language tag. Please refer to the MDN Docs for more info.

`locale_matcher`

Type: LocaleMatcher

The locale matching algorithm to use. Possible values are Lookup and BestFit; the default is BestFit. For information about this option, see the Intl page.

`calendar`

Type: Option<String>

The calendar to use, such as "chinese", "gregory", "persian" etc. For a list of the supported calendar types, see the MDN docs.

The way day periods should be expressed. This option only has an effect if a 12-hour clock (hour_cycle H11 or H12, or hour12 is true) is used. Note that the day period may be displayed even if the hour is not set to be displayed.

`numbering_system`

Type: Option<String>

The numbering system to use. Possible values include: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".

`hour12`

Type: Option<bool>

Whether to use 12-hour time (as opposed to 24-hour time). The default is locale dependent. This option overrides the hc language tag and/or the hour_cycle option in case both are present.

`hour_cycle`

Type: Option<HourCycle>

The hour cycle to use. This option overrides the hc language tag, if both are present, and the hour12 option takes precedence in case both options have been specified.

H11: hour system using 0–11; corresponds to midnight starting at 0:00 AM.
H12: hour system using 1–12; corresponds to midnight starting at 12:00 AM.
H23: hour system using 0–23; corresponds to midnight starting at 0:00.
H24: hour system using 1–24; corresponds to midnight starting at 24:00.

`time_zone`

Type: Option<String>

The time zone to use. The only value implementations must recognize is "UTC"; the default is the runtime’s default time zone. Implementations may also recognize the time zone names of the IANA time zone database, such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".

`format_matcher`

Type: FormatMatcher

The format matching algorithm to use. Possible values are Basic and BestFit; the default is BestFit. See the MDN docs for details. Only has an effect when using the individual date-time component options (and not UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style).

`weekday`

Type: Option<WeekdayFormat>

The representation of the weekday.

Long: e.g., Thursday
Short: e.g., Thu
Narrow: e.g., T. Two weekdays may have the same narrow style for some locales (e.g. Tuesday’s narrow style is also T).

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`era`

Type: Option<EraFormat>

The representation of the era.

Long: e.g., Anno Domini
Short: e.g., AD
Narrow: e.g., A

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`year`

Type: Option<YearFormat>

The representation of the year.

Numeric: e.g., 2012
TwoDigit: e.g., 12

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`month`

Type: Option<MonthFormat>

The representation of the month.

Numeric: e.g., 3
TwoDigit: e.g., 03
Long: e.g., March
Short: e.g., Mar
Narrow: e.g., M. Two months may have the same narrow style for some locales (e.g. May’s narrow style is also M).

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`day`

Type: Option<DayFormat>

The representation of the day.

Numeric: e.g., 1
TwoDigit: e.g., 01

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`hour`

Type: Option<TimeNumericFormat>

The representation of the hour.

Numeric: e.g., 1
TwoDigit: e.g., 01

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`minute`

Type: Option<TimeNumericFormat>

The representation of the minute.

Numeric: e.g., 1
TwoDigit: e.g., 01

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`second`

Type: Option<TimeNumericFormat>

The representation of the second.

Numeric: e.g., 1
TwoDigit: e.g., 01

Cannot be combined with UseIntlDateTimeFormatOptions::date_style / UseIntlDateTimeFormatOptions::time_style.

`fractional_second_digits`

Type: Option<u8>

The number of digits used to represent fractions of a second (any additional digits are truncated). Possible values are from 1 to 3.

`time_zone_name`

Type: Option<TimeZoneNameFormat>

The localized representation of the time zone name.

Long: long localized form (e.g., Pacific Standard Time).
Short: short localized form (e.g.: PST).
ShortOffset: short localized GMT format (e.g., GMT-8).
LongOffset: long localized GMT format (e.g., GMT-0800).
ShortGeneric: short generic non-location format (e.g.: PT).
LongGeneric: long generic non-location format (e.g.: Pacific Time).

`date_style`

Type: Option<DateTimeStyle>

The date formatting length. Cannot be combined with the individual date-time component options (weekday, era, year, month, day, hour, minute, second, fractional_second_digits, time_zone_name, day_period).

Possible values are Full, Long, Medium and Short.

`time_style`

Type: Option<DateTimeStyle>

The time formatting length. Cannot be combined with the individual date-time component options (weekday, era, year, month, day, hour, minute, second, fractional_second_digits, time_zone_name, day_period).

Possible values are Full, Long, Medium and Short.

Source

Source • Demo • Docs

Keyboard shortcuts