Getting Started with HelixUI

This guide provides an opinionated set of instructions for installing and setting up HelixUI and its dependencies for use in a simple static HTML project with the following assumptions.

A bundler is not being used.
The public/ directory is the web root for serving files via a web server.

1 - Installing HelixUI Assets

First and foremost, we need to obtain the assets required to configure our application.

To install HelixUI and its dependencies, run the following from the root of your project.

npm install helix-ui

Once complete, assets should be available in node_modules/helix-ui/.

2 - Copy Assets into App

Even though we've installed the required assets, they're not where the web server can serve them.

In order to serve the required assets, run the following commands from the root of your project.

# Web Components Polyfill Loader
cp node_modules/helix-ui/node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js public/vendor

# Web Components Polyfill Bundles (injected as needed by loader above)
cp -R node_modules/helix-ui/node_modules/@webcomponents/webcomponentsjs/bundles public/vendor

# production-ready, browser-compatible HelixUI JavaScript bundles
cp node_modules/helix-ui/dist/js/*.min.js public/vendor

# production-ready HelixUI Stylesheets
cp node_modules/helix-ui/dist/css/*.min.css public/vendor

Once complete, the directory structure of public/ should resemble the following:

public/
├ vendor/
│ ├ bundles/
│ │ └ ...
│ ├ helix-ui.min.css
│ ├ helix-ui.min.js
│ ├ helix-ui.module.min.js
│ └ webcomponents-loader.js
└ index.html

3 - Consuming Assets

Now that assets are in a location that can be served by a web server, we need to update public/index.html in order to make use of the assets.

3.1 - Add test content

To validate that assets are loading as we progress, let's add the following to the <body> of our markup.

<h1>Hello HelixUI!</h1>
<p>
  <hx-icon type="checkmark-circle"></hx-icon>
</p>

When viewed in a browser, the heading should be visible but you won't see any icon. This is because <hx-icon> hasn't been upgraded yet to a custom element (handled as part of HelixUI.initialize() functionality). We'll fix the icon in a later step.

3.2 - Load HelixUI Styles

To load HelixUI styles, add the following markup to the <head> element.

<link rel="stylesheet" href="vendor/helix-ui.min.css" />

If configured correctly, the <h1> element should be rendered in a thin, sans-serif font.

3.3 - Load Polyfills

The Web Components polyfills are built specifically to be run directly in the browser (uncompiled and unbundled). As such, we'll add the following markup to the <head> of our document.

<script src="vendor/webcomponents-loader.js"></script>

The webcomponents-loader.js polyfill script uses feature detection to identify the minimum polyfill bundle required by the current browser. If the browser requires polyfills, an additional <script> element (loading a polyfill bundle from vendor/bundles/) will be injected after the loader.

3.4 - Load HelixUI Scripts

In order to load HelixUI in a way that is compatible with the largest set of browsers, add the following markup to the bottom of the <body> element.

<!-- Legacy Browsers (ES5 UMD Module) -->
<script nomodule src="vendor/helix-ui.min.js"></script>
<script nomodule>
  HelixUI.initialize();
</script>

<!-- Modern Browsers (ES6 ES Module) -->
<script type="module">
  import HelixUI from '/vendor/helix-ui.module.min.js';

  HelixUI.initialize();
</script>

See the FAQ for more information about the different JavaScript bundles.

Once complete, <hx-icon> should render a visible SVG image.

4 - Verify Configuration

You've successfully configured your application to use HelixUI!

The markup in public/index.html should resemble the following markup.

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Step 3.2 -->
    <link rel="stylesheet" href="vendor/helix-ui.min.css" />

    <!-- Step 3.3 -->
    <script src="vendor/webcomponents-loader.js"></script>
    <!-- additional <script> may appear here -->
    <!--/Step 3.3 -->
  </head>
  <body>
    <!-- Step 3.1 -->
    <h1>Hello HelixUI!</h1>
    <p>
      <hx-icon type="checkmark-circle"></hx-icon>
    </p>
    <!--/Step 3.1 -->

    <!-- Step 3.4 -->
    <!-- Legacy Browsers (ES5 UMD Module) -->
    <script nomodule src="vendor/helix-ui.min.js"></script>
    <script nomodule>
      HelixUI.initialize();
    </script>

    <!-- Modern Browsers (ES6 ES Module) -->
    <script type="module">
      import HelixUI from '/vendor/helix-ui.module.min.js';

      HelixUI.initialize();
    </script>
    <!--/Step 3.4 -->
  </body>
</html>

Next Steps

Now that everything is wired up correctly, here are some suggestions for what to do next.

Configure a Layout to arrange page content consistently across your application.
Explore the documentation to learn how you can add meaningful interactivity to your application.