Migration guide
Version 1.2.0 includes a complete refactor of our JavaScript to modernize our code, and provides better compatibility with third-party frameworks, such as React and Angular. You can read more about the rationale and techniques in [this update][] link needed, but here are the notable changes:
All event handlers are managed with delegated event listeners
on the <body> element so any dynamically created elements will no longer need
to be re-initialized. For instance, if you're importing the accordion component
like so:
// ES5
var Accordion = require('uswds/src/js/components/accordion');
// or, in ES2015
import Accordion from 'uswds/src/js/components/accordion';And if you then use the Accordion constructor to re-initialize dynamically created
elements, then you can safely remove all of your accordion-related code — unless
you're also using the Accordion methods, show(), hide(), or hideAll().
These methods will remain available in v1.x for backwards compatibility, but the
API will change in v2.0.0.
For backwards compatibility with v1.x, the following JavaScript submodule APIs have been preserved, but will change in v2.0.0:
-
components/accordion will drop support for the exported
Accordionclass and methods. - components/navigation exports a function for backwards compatibility, but will export a behavior.
- components/search exports a function for backwards compatibility, but will export a behavior.
- components/validator exports a function for backwards compatibility, but will export a behavior.
- components/toggle-field-mask has been demoted to a utility function with a different API. The component submodule remains as a compatibility shim, but will be removed.
- components/toggle-form-input has been demoted to a utility function with a different API. The component submodule remains as a compatibility shim, but will be removed.
- We've replaced our
when-dom-readyutility with domready. The utils/when-dom-ready submodule remains for backwards compatibility with v1.x, but will be removed in v2.0.0. In the meantime, you can safelynpm install --save domreadyand replace all instances ofrequire('uswds/src/js/utils/when-dom-ready')withrequire('domready'). - The
dispatchutility is no longer used internally, and will be removed in v2.0.0. Rather than create per-element dispatch objects, you can use receptor (or our behavior utility function) to create reusable behaviors.
The Design System JavaScript now relies on several features of ES2015 (AKA ES6),
the next version of JavaScript. Many ES2015 features aren't yet supported
natively by some browsers, so if you're require()-ing the module or its submodules,
you'll need to ensure that your bundling or compiling tool supports converting
ES2015 to browser-friendly ES5. If you're using any of the following frameworks or
tools, this should require zero additional configuration:
- React uses Babel under the hood, so if you're using React, you're good to go.
- If you're using webpack version 2, then everything in your bundle will be automatically converted to ES5, because webpack 2 supports ES6 natively.
- If you're using webpack version 1, we suggest
migrating to version 2. Otherwise,
you'll need to use babel-loader
and configure it with
include: [require.resolve('uswds')]. More generally... - If you're already using Babel to compile your JavaScript, be sure that your
bundler also compiles third-party modules (i.e. anything in
node_modules). - If you're using Angular 2 or later, you're probably already using TypeScript, in which case...
-
TypeScript's
tsccompiler will automatically convert ES2015 to the target ECMAScript version, which defaults toES3. (Unless you're targeting IE9 or below, you can safely use--target ES5.)