React component for the moment date library.
- Installing
- Timezone Support
- Quick Start
- Props
- Pooled Timer
- Global Config
- Usage with React Native
- License
- Contributors
Use npm to install react-moment
along with its peer dependency, moment
.
npm install --save moment react-moment
The moment-timezone
package is required to use the timezone related functions.
npm install --save moment-timezone
Then import the package into your project.
import React from 'react';
import Moment from 'react-moment';
import 'moment-timezone';
export default class App extends React.Component {
...
}
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
const dateToFormat = '1976-04-19T12:59-0500';
<Moment>{dateToFormat}</Moment>
);
}
}
Outputs:
<time>Mon Apr 19 1976 12:59:00 GMT-0500</time>
The above example could also be written this way if you prefer to pass the date using an attribute rather than as a child to <Moment>
.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
const dateToFormat = '1976-04-19T12:59-0500';
<Moment date={dateToFormat} />
);
}
}
The date value may be a string, object, array, or Date
instance.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
const dateToFormat = new Date('1976-04-19T12:59-0500');
<Moment date={dateToFormat} />
);
}
}
The component supports the following props. See the Moment docs for more information.
interval={number}
By default the time updates every 60 seconds (60000 milliseconds). Use the interval
prop to change or disable updating.
Updates the time every 30 seconds (30000 milliseconds).
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment interval={30000}>
1976-04-19T12:59-0500
</Moment>
);
}
}
Disables updating.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment interval={0}>
1976-04-19T12:59-0500
</Moment>
);
}
}
format={string}
Formats the date according to the given format string. See the Moment docs on formatting for more information.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment format="YYYY/MM/DD">
1976-04-19T12:59-0500
</Moment>
);
}
}
Outputs:
<time>1976/04/19</time>
parse={string}
Moment can parse most standard date formats. Use the parse
attribute to tell moment how to parse the given date when non-standard. See the Moment docs on parsing for more information.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment parse="YYYY-MM-DD HH:mm">
1976-04-19 12:59
</Moment>
);
}
}
add={object}
subtract={object}
Used to add and subtract periods of time from the given date, with the time periods expressed as object literals. See the Moment docs on add and subtract for more information.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
const date = new Date();
return (
<div>
<Moment add={{ hours: 12 }}>{date}</Moment>
<Moment add={{ days: 1, hours: 12 }}>{date}</Moment>
<Moment subtract={{ hours: 12 }}>{date}</Moment>
<Moment subtract={{ days: 1, hours: 12 }}>{date}</Moment>
</div>
);
}
}
fromNow={bool}
Sometimes called timeago or relative time, displays the date as the time from now, e.g. "5 minutes ago".
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment fromNow>1976-04-19T12:59-0500</Moment>
);
}
}
Outputs:
<time>40 years ago</time>
Including ago
with fromNow
will omit the suffix from the relative time.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment fromNow ago>1976-04-19T12:59-0500</Moment>
);
}
}
Outputs:
<time>40 years</time>
from={string}
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment from="2015-04-19">1976-04-19T12:59-0500</Moment>
);
}
}
Outputs:
<time>39 years</time>
toNow={bool}
Similar to fromNow
, but gives the opposite interval.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment toNow>1976-04-19T12:59-0500</Moment>
);
}
}
Outputs:
<time>40 years ago</time>
to={string}
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment to="2015-04-19">1976-04-19T12:59-0500</Moment>
);
}
}
Outputs:
<time>39 years</time>
filter={function}
A function which modifies/transforms the date value prior to rendering.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
const toUpperCaseFilter = (d) => {
return d.toUpperCase();
};
return (
const dateToFormat = '1976-04-19T12:59-0500';
<Moment filter={toUpperCaseFilter}>{dateToFormat}</Moment>
);
}
}
Outputs:
<time>MON APR 19 1976 12:59:00 GMT-0500</time>
unix={bool}
Tells Moment to parse the given date value as a unix timestamp.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
const unixTimestamp = 198784740;
return (
<Moment unix>{unixTimestamp}</Moment>
);
}
}
Outputs:
<time>Mon Apr 19 1976 12:59:00 GMT-0500</time>
tz={string}
Sets the timezone. To enable server side rendering (SSR), client and server has to provide same datetime, based on common Timezone. The tz
attribute will enable set the common timezone.
import React from 'react';
import Moment from 'react-moment';
import 'moment-timezone';
exports default class MyComponent extends React.Component {
render() {
const unixTimestamp = 198784740;
return (
<Moment unix tz="America/Los_Angeles">
{unixTimestamp}
</Moment>
);
}
}
Outputs:
<time>Mon Apr 19 1976 09:59:00 GMT-0800</time>
locale={string}
Sets the locale used to display the date.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
const dateToFormat = '1976-04-19T12:59-0500';
return (
<Moment locale="de">{dateToFormat}</Moment>
);
}
}
Note In some cases the language file is not automatically loaded by moment, and it must be manually loaded. For example, to use the French locale, add the following to your bootstrap (e.g. index.js) script.
import 'moment/locale/fr';
element={string|React.Component}
The element type to render as (string or function).
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment element="span">1976-04-19T12:59-0500</Moment>
);
}
}
Outputs:
<span>Mon Apr 19 1976 12:59:00 GMT-0500</span>
onChange={func}
The onChange
prop is called each time the date is updated, which by default is every 60 seconds. The function receives the new date value.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment onChange={(val) => { console.log(val); }}>
1976-04-19T12:59-0500
</Moment>
);
}
}
Any other properties are passed to the <time>
element.
import React from 'react';
import Moment from 'react-moment';
exports default class MyComponent extends React.Component {
render() {
return (
<Moment className="datetime" aria-hidden={true}>
1976-04-19T12:59-0500
</Moment>
);
}
}
Outputs:
<time class="datetime" aria-hidden="true">Mon Apr 19 1976 12:59:00 GMT-0500</time>
By default a timer is created for each mounted <Moment />
instance to update the date value, which is fine when you only have a few instances on the page. However, performance can take a hit when you have many mounted instance. The problem is solved by using a pooled timer.
When pooled timing is enabled, react-moment will only use a single timer to update all mounted <Moment />
instances. Pooled timing is enabled by calling startPooledTimer()
and stopped by calling clearPooledTimer()
.
Call the startPooledTimer()
static method from your bootstrapping script (usually index.js) to initialize the timer.
import React from 'react';
import ReactDOM from 'react-dom';
import Moment from 'react-moment';
import App from './components/app';
// Start the pooled timer which runs every 60 seconds
// (60000 milliseconds) by default.
Moment.startPooledTimer();
// Or set the update interval. This will update the mounted
// instances every 30 seconds.
// Moment.startPooledTimer(30000);
ReactDOM.render(<App />, document.getElementById('mount'));
Note: The interval
prop set on each <Moment />
instance is ignored when using pooled timing, except where interval={0}
to disable updating.
Note: The startPooledTimer()
method must be called before any <Moment />
instances are mounted.
Some prop values may be set globally so you don't have to set them on every react-moment instance.
- globalLocale
- globalFormat
- globalParse
- globalFilter
- globalElement
import React from 'react';
import ReactDOM from 'react-dom';
import Moment from 'react-moment';
// Set the locale for every react-moment instance to French.
Moment.globalLocale = 'fr';
// Set the output format for every react-moment instance.
Moment.globalFormat = 'D MMM YYYY';
// Use a <span> tag for every react-moment instance.
Moment.globalElement = 'span';
// Upper case all rendered dates.
Moment.globalFilter = (d) => {
return d.toUpperCase();
};
const App = () => (
<Moment>1976-04-19T12:59-0500</Moment>
);
ReactDOM.render(<App />, document.getElementById('mount'));
You can override the global values on a per-instance basis using regular props.
import React from 'react';
import ReactDOM from 'react-dom';
import Moment from 'react-moment';
// Set the locale for every react-moment instance to French.
Moment.globalLocale = 'fr';
const App = () => (
<div>
{/*
Renders using the 'fr' locale due to the global setting.
*/}
<Moment>1976-04-19T12:59-0500</Moment>
{/*
Overrides the global locale and uses 'en' instead.
*/}
<Moment locale="en">1976-04-19T12:59-0500</Moment>
</div>
);
ReactDOM.render(<App />, document.getElementById('mount'));
If you are using React Native then you'll have to pass in Text
.
import Moment from 'react-moment';
import { Text } from 'react-native';
Then:
<Moment element={Text} >1976-04-19T12:59-0500</Moment>
This software is released under the MIT license. See LICENSE for more details.