Fork me on GitHub


Introduction to Uranium

Uranium offers web page authors the ability to add several convenient JavaScript interactions to the HTML elements on their pages, without writing a single line of JavaScript.

For example, you might have a page with a set of sub-sections that each have headers followed by related content, one right after the other. With the Uranium toggler interaction, you could transform that into an accordion just by adding a few data attributes to the existing HTML elements.

Uranium interactions are not opinionated about styling and layout. You should be able to add the Uranium script and a few data attributes to practically any working web page that uses jQuery (as far back as version 1.3), and take advantage of these useful interactions right where you need them most.

Basic Requirements

Since Uranium builds on jQuery, the minimum you need to do to get Uranium working on your page is to include the latest jQuery script followed by the Uranium script. A good place to do this is right before the closing tag for the body element on your HTML document.

        <title>Uranium Sample Page</title>
        <div data-ur-set="toggler">
          <h1 data-ur-toggler-component="button">This is your page</h1>
          <p data-ur-toggler-component="content">And this is the content of your page</p>
        <script src="scripts/jquery-1.9.1.min.js"></script>
        <script src="scripts/jquery.uranium.js"></script>

Just download the latest minified version of jQuery, and the Uranium script, and save them in your scripts directory. Then reference them in your HTML document, and you should be good to go.

If there's a conflict with another jQuery version, you can either remove one of them or separate one from the global namespace:

      <script src="scripts/jquery.uranium.js"></script>
      <script>Uranium.$ = $.noConflict(true);</script>

Data Attributes

Data attributes can be added to any HTML element. We use data attributes instead of modifying the id or class attributes of HTML elements so that Uranium can be injected into existing pages as easily as it can be added to new pages, without affecting existing styles and JavaScript.

The syntax is simple. Just add the data attributes the same way you would add any other attributes to an HTML element. For example, to tell Uranium that a specific <h2> element should be used as a toggle button to show and hide the following paragraph, you might start with something like this:

        <p>This is content we want to hide and show</p>

… and end up with something like this.

      <div data-ur-set="toggler">
        <h2 data-ur-toggler-component="button">Information</h2>
        <p data-ur-toggler-component="content">This is content we want to hide and show</h2>

Just adding those data attributes to a page that has jQuery and the Uranium script loaded would enable the desired interaction.

Interaction Sets and Components

Every interaction has at its core a set and a series of components. The set is unique for every interaction: data-ur-set="toggler" for the toggler interaction, etc. The set attribute should be used to wrap the whole interaction.

There are usually a few components per interaction. Some may be required to get the interaction to work, but most are usually optional. For example, a toggler has a button and content, and at least one of each is required if you want the interaction to work. Components are designated in the following way: they'll have data-ur-{interaction}-component="thing".

Most of the interactions also have some extra options. For example, carousel has an optional data-ur-carousel-component="count", which is used to display the count of the currently selected item in a carousel.

Additional Resources


To familiarize yourself with how Uranium can be added to a page, we've written up some tutorials demonstrating how to work through a basic and an advanced Uranium use-case. As you'll see, even the advanced example follows the same basic philosophy, allowing you to integration useful JavaScript interactions just by adding a few declarative elements to your HTML.

Basic Use
Creating a simple toggler
Advanced Use
Building a custom carousel with optional features

Additional Documentation

We've written up some more detailed notes on some of the ways in which Uranium is unique. Uranium is not trying to be all things to all people, but for those who need something lightweight, unopinionated, and focused on injecting simple interactions in a declarative manner, Uranium just may be the answer.

The guiding philosophy behind Uranium and the interactions we support
general information about the model on which all the interactions are based
"lazy" and "explicit" styling of interactions
when to use sets and when to use IDs