Skip to navigation Skip to navigation Skip to content

Welcome to Hydrogen! #

npm (tag) Netlify

Thanks for visiting Hydrogen's documentation! This site contains everything you'll need to install Hydrogen on your project, create a theme, run commands, style your interfaces, and troubleshoot common problems.

Have a question but can't find the answer here? Submit a ticket on Github and perhaps the community can provide some insight. We'd also love to receive feedback on how this documentation can be improved.

Recent updates #

Learn more about the latest and greatest releases containing new features, optimized tooling, bugfixes, and a better overall experience.

Featured release #

2.0.0 #

This release reworks almost every single feature and option, enabling more reliable output, faster compile times, and loads of new features and options.

major Released: February 1, 2023 🚨 Breaking

✨ New features (9) #
  • Breaking: Hydrogen 2.0.0 represents a completely new approach to CSS that differs drastically from version 1.0.0.
    • Rather than compiling a Sass library and then selectively generating a CSS file for your project, Hydrogen now actively parses data-h2 attribute values using JavaScript and creates CSS on the fly.
    • This approach is significantly faster and more accurate than the previous approach and opens up a world of new possibilities that you can discover in the 2.0.0 documentation.
  • While version 1.0.0 supported over 25 different style properties, this release shatters that limitation by enabling support for every single CSS property out there.
    • Not only can you use any CSS property at your disposal, 2.0.0 supports the use of configured settings
  • 2.0.0 introduces new functionality that enables support for custom, automatically applied themes.
    • By adding the theme's key value to your site's data-h2 wrapper attribute, you can restyle your project in seconds.
    • This functionality also enables the ability to specify unique styles per-theme, meaning you can alter layouts, media, and more.
  • Alongside themes, 2.0.0 also adds support for configuring values that apply to dark mode automatically.
    • This feature also allows you to control how dark mode is applied; whether through media queries or a manual toggle.
    • Each theme you define has access to its own unique styles for light and dark modes, allowing you to customize them as much as you need.
  • 2.0.0 introduces new query-specific references that allow more granular control over the target of your styles.
    • The :selectors[] allows you to apply styles only if the element contains specific selectors (classes, ids, attributes).
    • The :children[] allows you to apply styles to children nested inside the current element, allowing you to bulk style similar elements.
  • A new vertical rhythm and typography system has been implemented that allows you to granularly control how typography appears on your project on a per-media query basis.
    • These typography settings now also directly impact and inform an automatically generated heading typography scale that accounts for default line height.
    • New whitespace multipliers have been added that allow you to apply multiples of your base line-height as units of space, creating unity and consistency between the interface and the typography.
  • Color configurations have been overhauled and improved through the addition of color modifiers.
    • Out of the box, for each of your color configurations, Hydrogen generates 6 alternate colors: light, lighter, lightest, dark, lighter, darkest.
    • Color opacity modifiers have also been improved and now support dynamic calculation, meaning they are no longer limited to fixed values.
    • Alongside default modifiers, you can now also define custom modifiers for your colors, allowing you to set unique values for specific contexts.
  • 2.0.0 introduces a handful of helpful validation steps to help catch unexpected errors in your code.
    • Hydrogen will now validate your configuration file before each run to ensure there aren't any syntax errors.
    • It will also validate each attribute's parsed CSS to try and catch invalid CSS syntax.
  • Hydrogen's CLI commands now accept a series of optional flags, allowing you to customize the output based on environment and build contexts.
🛠️ Optimizations (5) #
  • Hydrogen's documentation has been completely rebuilt from the ground up using 11ty.
  • CSS construction has been improved to leverage the use of CSS variables throughout, allowing for greater control and manipulation by both the system and the end user.
  • The system's code structure and documentation have been significantly improved and organized for better maintenance, debugging, and community contribution.
  • 2.0.0 updates and enhances Hydrogen's console output. Along with more helpful output, you'll find new formatting, configurable settings, detailed timers, and more.
  • Hydrogen now offers a new debugging tool that generates log files containing parsed data that can offer insight into where the tool might be failing.

Latest stable release #

2.1.0 #

This minor release enhances the query configuration so that you can configure more than just media queries, adds a few quality of life features, fixes a few bugs, and updates the documentation site.

minor Released: July 9, 2024 ⚠️ Warning

✨ New features (5) #
  • Allows for other @rule configurations in the media settings, which enables the use of container queries.
  • Exports the build and watch scripts from the module's main index file.
  • Hydrogen now returns its processed CSS as a string for use by other frameworks.
  • Allows you to control whether Hydrogen writes a CSS file.
  • Adds the ability to toggle Lightning CSS' error recovery to prevent it from exiting the build.
🛠️ Optimizations (2) #
  • Centralizes results logging to help make output more consistent.
  • Deprecates data-h2-container custom syntax in favor of the native CSS property; adds data-h2-wrapper as a replacement for the custom syntax.
🪲 Bugfixes (2) #
  • Warning: Addresses inconsistencies created by the random order of the cascade generated based on file-read order.
    • All properties are now written in alphabetical order, which forces shortcut properties (e.g. margin) to always be overridden by their specific variants (e.g. margin-right).
    • In practice, this means that if you apply a shortcut property and one or more of its variants to the same element, the specific variants will always take precedence.
    • This change is labelled with a warning because Hydrogen's output order is liable to change, meaning certain projects might experience a swap in the way overridden properties display.
  • Fixes a bug where the build would log as "succeeded" when warnings were output.
📚 Documentation (2) #
  • Reworks the homepage layout with a reduced header and updated copy.
  • Adds new information about incompatibilities between flex-grid and margin.

Made in Canada by humans like you.