formatjs/formatjs v1.1.0 on GitHub

This release adds a declarative way to format data and strings via React Intl Components and JSX, and it's fully backwards compatible with v1.0.x!

The other high-level integrations in FormatJS (Handlebars and Dust) provide a way to declaratively format data and strings, but for v1.0.0 of React Intl you had to use a mixin that provided imperative format* methods. Now with v1.1.0 there's a declarative way using React Intl Components with JSX:

var IntlMixin        = ReactIntl.IntlMixin;
var FormattedNumber  = ReactIntl.FormattedNumber;
var FormattedMessage = ReactIntl.FormattedMessage;

var msg = 'Hello, {name}!';

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <ul>
                <li><FormattedNumber value={0.9} style="percent" /></li>
                <li><FormattedMessage msg={msg} name={<b>Eric</b>} /></li>
            </ul>
        );
    }
});

We find that using the React Intl Components feels much more idiomatic and more powerful (more on that below). Thanks to @sebmarkbage for suggesting the idea! See: #23 for the details.

The docs on the website has been updated to reflect the recommended way to use React Intl.

A New Global: `ReactIntl`

Now that React Intl has grown to be more than just a mixin we decided to change the named of the global object that's create from ReactIntlMixin to ReactIntl. We still expose the old global for backwards compatibility, it simply points to ReactIntl.IntlMixin.

Note: The globals are only exposed in React Intl's dist/ files, if you're using a module system or bundler like Browserify globals won't be exposed by default.

The New React Intl Components

In order to add a way declaratively format data and strings in React we needed to create React Components. These components map to the format* methods the IntlMixin provides but enables you to format things by writing JSX.

There were a couple iterations on how these components should work (#60 and #65), and we settled on making them all self-closing and have noun name prefixed with "Formatted". Here's the set of React Intl Components:

<FormattedDate> formats a date value
<FormattedTime> formats a date value with time formats
<FormattedRelative> formats a date relative to now; e.g. "3 hours ago"
<FormattedNumber> formats a number value
<FormattedMessage> formats a translated string message
<FormattedHTMLMessage> formats a translated string message

The new components added ~1kb gz to React Intl, bringing the library to 7.7kb gz, but we think it's well worth the added size.

Formatting Rich-Text Strings

When formatting string messages using the formatMessage() method, a string is returned. This will work for many strings, but sometimes string messages benefit from being rendered as rich-text. React Intl supports formatting rich-text strings in the following ways:

React Elements as `props` Values

A long standing issue (#26) has been that there was no good way to render other React Elements inside of a formatted message, now there is when using either the <FormattedMessage> or <FormattedHTMLMessage> components.

The recommended way to format strings as rich-text is to use the <FormattedMessage> Component, and pass other React Elements as props values to be used to fill-in placeholders in the static message string.

Here's a simple example where we make the name bold:

<FormattedMessage message="Hello, {name}!" name={<b>Eric</b>} />

Checkout the website for more complex examples.

HTML in Static ICU Message Strings

In some cases you might want to put HTML directly into the static ICU Message String, while we recommend you use the nested React Elements approach mentioned about React Intl provides a <FormattedHTMLMessage> Component.

Note: <FormattedHTMLMessage> only supports HTML in the static ICU Message string, it does not support JSX. Also, using this component is less performant than using <FormattedMessage> because it has to opt-out of React's virtual DOM diffing.

Browserify/Webpack + ES3 Environments

It's very common for React apps to use Browserify/Webpack to bundle up their app code and dependencies for the browser. In previously releases we made sure that React Intl bundled correctly when using these tools, but recently we got reports that things broke in IE8. In this release we've fixed all those issue and add Browserify smoke tests that run in all the major via the CI process.

Browserify/Webpack bundling is something we want to support, so if you find an problem with it be sure to open an issue so it can get fixed.

Fixed Minified Source Maps

Fixed source maps for minified files but updating the build process to make sure the source content is actually included in the .map files.

Checkout the full set of changes since the last release for all the details.

Thanks to everyone who tested out the v1.1.0-rc-* releases, your feedback made this release solid!

formatjs/formatjs v1.1.0 v1.1.0 — React Intl Components on GitHub

A New Global: ReactIntl