Localized relative date/time formatting in React
Date into a string like "1 day ago". In any language.
sh
$ npm install react-time-ago --save
`
Alternatively, one could include it on a web page directly via a tag.
Use
To begin, decide on the set of languages that your application will be translated into. For now, let's assume that it's gonna be just English.
Then, for each of those languages, import the language data:
`js
// Adds support for English language.
import "react-time-ago/locale/en"
`
Now you're ready to render a component for any of those languages.
`js
import React from "react"
import ReactTimeAgo from "react-time-ago"
export default function Example({ date }) {
return (
Last seen:
)
}
`
To change the output style, pass a timeStyle property: see the list of available formatting styles.
The label will automatically refresh itself.
Hook
If you prefer using a React Hook rather than a React Component, the parameters for it are the same as the props for the React component, excluding:
* tooltip: boolean
* component: React.Component
* wrapperComponent: React.Component
* wrapperProps: object
Example:
`js
import { useTimeAgo } from 'react-time-ago'
const result = useTimeAgo(parameters)
`
The hook returns an object with properties:
* date: Date — Same as the date input parameter. If the input parameter was a timestamp (number) then it gets converted to a Date.
* formattedDate: string — Formatted date. Example: "5 min ago".
* verboseDate: string — Formatted date (verbose variant). Example: "Thursday, December 20, 2012, 7:00:00 AM GMT+4".
React Native
By default, this component renders a HTML element. When using this component in React Native, a developer should pass a custom component property that will be used instead of the HTML element. Example:
`js
import React from 'react'
import PropTypes from 'prop-types'
import ReactTimeAgo from 'react-time-ago'
export default function TimeAgo(props) {
return
}
function Time({ date, verboseDate, tooltip, children }) {
return {children}
}
Time.propTypes = {
date: PropTypes.instanceOf(Date).isRequired,
verboseDate: PropTypes.string,
tooltip: PropTypes.bool.isRequired,
children: PropTypes.string.isRequired
}
`
Tooltip
By default, a standard HTML title attribute is used to display a tooltip with the verbose date on when the user hovers the label.
If such "native" tooltip doesn't fit the application's design, a custom tooltip component could be rendered. For that, supports properties:
* tooltip={false} — Instructs the component to not add an HTML title attribute.
* wrapperComponent — Should be a React component that will wrap the label.
* Properties:
* children — Example:
* verboseDate: string — Example: "Wednesday, January 1, 2000, 10:45:10 PM"
* wrapperProps — If defined, these properties are simply passed through to the wrapperComponent.
Here's an example that renders a react-responsive-ui/Tooltip instead of a "native" HTML title tooltip:
`js
import React from 'react'
import PropTypes from 'prop-types'
import Tooltip from 'react-responsive-ui/commonjs/Tooltip'
import ReactTimeAgo from 'react-time-ago'
import 'react-time-ago/Tooltip.css'
export default function ReactTimeAgoWithTooltip(props) {
return (
wrapperComponent={TooltipContainer}
tooltip={false}/>
)
}
const TooltipContainer = ({ verboseDate, children, ...rest }) => (
{children}
)
TooltipContainer.propTypes = {
// verboseDate is not generated on server side
// (because tooltips are only shown on mouse over),
// so it's not declared a "required" property.
verboseDate: PropTypes.string,
children: PropTypes.node.isRequired
}
`
Past vs Future
When given a past date, .format() returns an "... ago" label.
When given a future date, .format() returns an "in ..." label.
`js
60 1000}/>
// "in 5 minutes"
`
When given a "now" date, which is neither past, nor future, .format() doesn't really know how it should represent the time difference — as -0 or as +0.
By default, it treats it as -0, meaning that it will return "0 seconds ago" rather than "in 0 seconds".
To instruct .format() to treat it as +0, pass future: true parameter.
`js
// Without future: true
// "just now"
// With future: true
// "in a moment"
`
CDN
To include this library directly via a tag on a page, one can use any npm CDN service, e.g. unpkg.com or jsdelivr.com
`html
`
Props
`js
// date: Date or timestamp: number.
// E.g. new Date() or 1355972400000.
date: PropTypes.oneOfType([
PropTypes.instanceOf(Date),
PropTypes.number
]).isRequired,
// Preferred locale.
// Is 'en' by default.
// E.g. 'ru-RU'.
locale: PropTypes.string,
// Alternatively to locale, one could pass locales:
// A list of preferred locales (ordered).
// Will choose the first supported locale from the list.
// E.g. ['ru-RU', 'en-GB'].
locales: PropTypes.arrayOf(PropTypes.string),
// When future is set to true and date is equal to Date.now(),
// it will format it as "in 0 seconds" rather than "0 seconds ago".
future: PropTypes.bool,
// Date/time formatting style.
// See javascript-time-ago docs on "Styles" for more info.
// E.g. 'round', 'round-minute', 'twitter', 'twitter-first-minute'.
timeStyle: PropTypes.oneOfType([
PropTypes.string,
PropTypes.object
]),
// round parameter of javascript-time-ago.
// See javascript-time-ago docs on "Rounding" for more info.
// Examples: "round", "floor".
round: PropTypes.string,
// When freezeAt timestamp is specified, the label will stop refreshing
// itself when Date.now() becomes equal to freezeAt.
// For example, if freezeAt = Date.now() + 60 * 1000 is passed,
// the label will refresh itself for 1 minute, after which it will freeze
// and stop refreshing itself.
freezeAt: PropTypes.number,
// A React component to render the relative time label.
// Receives properties:
// * date: Date — The date.
// * verboseDate: string — Formatted verbose date.
// * tooltip: boolean — The tooltip property of component.
// * children: string — The relative time label.
// * All "unknown" properties that have been passed to are passed through to this component.
component: PropTypes.elementType,
// Whether to use HTML tooltip attribute to show a verbose date tooltip.
// Is true by default.
// Can be set to false to disable the native HTML tooltip.
tooltip: PropTypes.bool,
// Verbose date formatter.
// By default it's (date) => new Intl.DateTimeFormat(locale, {…}).format(date).
formatVerboseDate: PropTypes.func,
// Intl.DateTimeFormat format for formatting verbose date.
// See Intl.DateTimeFormat docs for more info.
verboseDateFormat: PropTypes.object,
// (deprecated)
// How often the component refreshes itself.
// When not provided, will use getNextTimeToUpdate() feature
// of javascript-time-ago styles to determine the update interval.
updateInterval: PropTypes.oneOfType([
PropTypes.number,
PropTypes.arrayOf(PropTypes.shape({
threshold: PropTypes.number,
interval: PropTypes.number.isRequired
}))
]),
// (deprecated).
// Set to false to disable automatic refresh of the component.
// Is true by default.
// I guess no one actually turns auto-update off, so this parameter is deprecated.
tick: PropTypes.bool,
// Allows setting a custom baseline for relative time measurement.
// https://gitlab.com/catamphetamine/react-time-ago/-/issues/4
now: PropTypes.number,
// Allows offsetting the date by an arbitrary amount of milliseconds.
// https://gitlab.com/catamphetamine/react-time-ago/-/issues/4
timeOffset: PropTypes.number,
// Pass false to use native Intl.RelativeTimeFormat / Intl.PluralRules
// instead of the polyfilled ones in javascript-time-ago.
polyfill: PropTypes.bool,
// (advanced)
// A React Component to wrap the resulting React Element.
// Receives verboseDate and children properties.
// Also receives wrapperProps, if they're passed.
// verboseDate can be used for displaying verbose date label
// in an "on mouse over" (or "on touch") tooltip.
// See the "Tooltip" readme section for more info.
// Another example could be having wrapperComponent
// being rerendered every time the component refreshes itself.
wrapperComponent: PropTypes.elementType,
// Custom props passed to wrapperComponent.
wrapperProps: PropTypes.object
``