Skip to navigation Skip to navigation Skip to content

Syntax overview

Learn about an attribute is constructed and how they enable styling.

Parts of an attribute #

Hydrogen's unique approach to applying styles takes advantage of the key-value pair provided by custom data attribute selectors. This key-value setup allows Hydrogen to remain legible without sacrificing complexity when its required.

index.html 
1
2
3
<button data-h2-background="base(primary)">
  Hello
</button>

Attribute syntax #

Hydrogen attributes consist of 3 main elements:

  • data-h2- is the custom, namespaced data attribute's prefix.
  • property is the CSS property you'd like to style.
  • query() represents one or more media queries containing styles that should be applied to the selected property.
1
<p data-h2-property="query() ..."></p>

Query syntax #

Queries have their own syntax and range from extremely simple (e.g. base()) to extremely specific (e.g. p-tablet:dark:hover:selectors[.active]()). They are constructed from the following elements:

1
media:mode:state:selectors[]:children[](options)
  • media is the only required value for a query and specifies which media query to apply styles to. Generally, you'll be using the base() query for most of your styling.
1
base()
  • :mode allows you to target modes like dark mode. This value is optional and omitting it applies styles to the default light mode.
    • :all will force the style to remain the same across light and dark modes.
    • :dark will apply the style to dark mode only.
1
base:dark()
  • :state allows you to target standard markup states supported by HTML such as :hover and :focus-visible.
1
base:hover()
  • :selectors[] allows you to specify a comma-separated list of IDs, classes, or attributes that must be present on the element in order for the styles to apply.
1
base:selectors[.active, #target]()
  • :children[] accepts a comma-separated list of elements as well as IDs, classes, or attributes, but will target nested elements containing the specified selectors.
1
base:children[button]()
  • (options) are the actual styles you'd like to apply to the property. Barring a handful of custom properties unique to Hydrogen, you can use standard CSS syntax here.
1
data-h2-padding="base(5px)"

Using attributes in your code #

Generally speaking, you'll be writing Hydrogen attributes within markup or markup files such as html. This means that you can apply Hydrogen attributes to any element like you would other data attributes. Hydrogen attributes should live next to your classes, ids, and other common attributes.

A basic example #

While the syntax can be daunting at first, a majority of the time you'll be using relatively simple iterations of Hydrogen's data attributes. Sometimes examples are the easiest way to learn, so we've provided a few attributes of increasing complexity.

Let's start by applying your primary brand color to some text. To do so, we'll use the data-h2-color attribute, which only accepts one option, color. We'll set this option as primary inside the base media query.

index.html 
1
<p data-h2-color="base(primary)">My text</p>

Great! Now let's try something a little more advanced. Perhaps we'd like our text to change to our secondary brand color on desktop devices. We can achieve this by adding another media query inside of the attribute.

index.html 
1
2
3
<p data-h2-color="base(primary) desktop(secondary)">
  My text
</p>

To take it a step further, how about we make our text white for users who prefer dark mode? We can achieve this by adding the :dark modifier to a new base query.

Hydrogen's data attributes can be as simple or as complex as you need them to be given the design of the interface. Sometimes setting a single option in the base query is enough, while other situations might require different options for every query, mode, and state you have access to.

index.html 
1
2
3
<p data-h2-color="base(primary) base:dark(white) desktop(secondary)">
  My text
</p>

Working with markup #

Using Hydrogen attributes in your markup is the most common way to add styles to your project.

For example, lets say we have a delete button in our HTML file and want to apply a red background color to help make it clear that the button causes a destructive action.

index.html 
1
2
3
4
5
<button
  onclick="delete()"
  data-h2-background="base(red)">
  Delete button
</button>

Working with JavaScript #

You can also use Hydrogen attributes as key/value pairs in your code. This is especially helpful when working in JavaScript or JSX, because it allows you to create reusable maps of attributes that can then be expanded in your markup.

For example, let's say we have an alert component and we want to apply Hydrogen attributes based on its state of success or error.

By assigning Hydrogen key/value pairs to the alertTypes object, we can use them to apply styles based on the alert's type prop that is passed in later.

app.js 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const alertTypes = {
  success: {
    "data-h2-background-color": "base(success)",
    "data-h2-color": "base(success.dark)",
  },
  error: {
    "data-h2-background-color": "base(error)",
    "data-h2-color": "base(error.dark)",
  },
};

class Alert extends React.Component {
  render() {
    return (
      <div {...alertTypes[this.props.alertType]}>My alert text</div>
    );
  }
};

Parsing limitations #

The one thing to note is that it's important that Hydrogen attributes are included in full wherever you use them. Hydrogen scrapes your code to build your CSS, and this means it needs to be able to parse the property in tandem with its options. Separating the options out into variables like the example provided will not work and Hydrogen will ignore the value.

This limitation applies to templating languages as well - be sure to include attributes in their entirety when defining them, whether on an element or in a variable.

🚫 Hydrogen will not parse this 
1
2
3
4
5
6
7
8
9
var my_value = "base(blue)"

class Alert extends React.Component {
  render() {
    return (
      <div data-h2-color={my_value}>My alert text</div>
    );
  }
};

VS Code snippets #

Hydrogen also provides a handy VS Code-compatible snippets file that makes adding attributes to your code a breeze. Once added, you can begin typing h2- in your code and tab complete any property available to you. If you find a CSS property that isn't included in the autocomplete, Hydrogen will still parse it properly.

The snippets provide helpful prompts for the syntax, making remembering what you need fast and easy. We recommend adding the snippets to your project files to make them available to anyone working on your code, but you can also add them as a global snippets file if you choose to.

To add snippets to your local project:

  1. In your project folder, create a .vscode folder if one doesn't already exist
  2. Create a file in that folder named hydrogen.code-snippets
  3. Paste the snippets data into the file
  4. Save

To add snippets to VS Code globally:

  1. In VS Code, hit CTRL+SHIFT+P to open the command palette
  2. Select "Configure User Snippets"
  3. Select "New Global Snippets File..."
  4. Enter a file name (e.g. hydrogen)
  5. Paste the snippets data into the file
  6. Save

Previously

« Styling