Format Relative Time

npm2.0.0

The format-relative-time component displays relative time (e.g., "2 hours ago", "in 3 days") using the Intl.RelativeTimeFormat API.

Example

2026-01-01T19:45:09.581Z

2025-12-31T21:45:09.581Z

2026-01-04T21:45:09.581Z

code

<script type="module">
  import '@blueprintui/components/include/format-relative-time.js';
</script>

<div bp-layout="block gap:md">
  <bp-format-relative-time>2026-01-01T19:45:09.581Z</bp-format-relative-time>

  <bp-format-relative-time>2025-12-31T21:45:09.581Z</bp-format-relative-time>

  <bp-format-relative-time>2026-01-04T21:45:09.581Z</bp-format-relative-time>
</div>

Numeric Format

2025-12-31T21:45:09.602Z

code

<script type="module">
  import '@blueprintui/components/include/format-relative-time.js';
</script>

<div bp-layout="block gap:md">
  <bp-format-relative-time numeric="auto">2025-12-31T21:45:09.602Z</bp-format-relative-time>

  <bp-format-relative-time numeric="always">2025-12-31T21:45:09.602Z</bp-format-relative-time>
</div>

Style Variations

2026-01-01T19:45:09.617Z

code

<script type="module">
  import '@blueprintui/components/include/format-relative-time.js';
</script>

<div bp-layout="block gap:md">
  <bp-format-relative-time format-style="long">2026-01-01T19:45:09.617Z</bp-format-relative-time>

  <bp-format-relative-time format-style="short">2026-01-01T19:45:09.617Z</bp-format-relative-time>

  <bp-format-relative-time format-style="narrow">2026-01-01T19:45:09.617Z</bp-format-relative-time>
</div>

Specific Unit

2025-12-30T21:45:09.608Z

code

<script type="module">
  import '@blueprintui/components/include/format-relative-time.js';
</script>

<div bp-layout="block gap:md">
  <bp-format-relative-time unit="auto">2025-12-30T21:45:09.608Z</bp-format-relative-time>

  <bp-format-relative-time unit="hour">2025-12-30T21:45:09.608Z</bp-format-relative-time>

  <bp-format-relative-time unit="day">2025-12-30T21:45:09.608Z</bp-format-relative-time>
</div>

Live Sync

2026-01-01T21:44:09.599Z

code

<script type="module">
  import '@blueprintui/components/include/format-relative-time.js';
</script>

<div bp-layout="block gap:md">
  <bp-format-relative-time>2026-01-01T21:44:09.599Z</bp-format-relative-time>

  <bp-format-relative-time sync>2026-01-01T21:44:09.599Z</bp-format-relative-time>
</div>

Future Date

2026-01-02T21:45:09.587Z

2026-01-08T21:45:09.587Z

code

<script type="module">
  import '@blueprintui/components/include/format-relative-time.js';
</script>

<div bp-layout="block gap:md">
  <bp-format-relative-time>2026-01-02T21:45:09.587Z</bp-format-relative-time>

  <bp-format-relative-time>2026-01-08T21:45:09.587Z</bp-format-relative-time>
</div>

Inline Text

Last updated2026-01-01T20:45:09.594Z

code

<script type="module">
  import '@blueprintui/components/include/format-relative-time.js';
</script>

<p bp-text="content">Last updated <bp-format-relative-time format-style="short">2026-01-01T20:45:09.594Z</bp-format-relative-time></p>

Install

NPM

// npm package
import '@blueprintui/components/include/format-relative-time.js';

CDN

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/@blueprintui/components/include/format-relative-time.js/+esm';
</script>

bp-format-relative-time

Properties

Name	Types	Description
`numeric`	`'always' \| 'auto'`	determines how to format the time: 'auto' shows "yesterday" vs "1 day ago"
`formatStyle`	`'long' \| 'short' \| 'narrow'`	determines the formatting style: 'long', 'short', or 'narrow'
`unit`	`'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'year' \| 'auto'`	the time unit to use, or 'auto' to automatically select the best unit
`sync`	`boolean`	auto-update the displayed time at appropriate intervals
`locale`	`string`	locale to use for formatting

Attributes

Name	Types	Description
`numeric`	`'always' \| 'auto'`	determines how to format the time: 'auto' shows "yesterday" vs "1 day ago"
`format-style`	`'long' \| 'short' \| 'narrow'`	determines the formatting style: 'long', 'short', or 'narrow'
`unit`	`'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'year' \| 'auto'`	the time unit to use, or 'auto' to automatically select the best unit
`sync`	`boolean`	auto-update the displayed time at appropriate intervals
`locale`	`string`	locale to use for formatting