Loading haxcellence..

Using hax cli you can create a custom theme for your site.

This will create a new site called coolstuff and a theme for it. To edit your theme use the following developer workflow:

• hax site start --root ./coolstuff -- this gets HAX running so you can edit pages / see your site
• cd coolstuff/custom && npm start -- this gets the files being watched and rebuilt for your theme
• You can edit coolstuff/custom/src/custom-coolstuff-theme.js to work on your theme

Considerations

• you can add additional outside projects, just make sure they are not already leveraged in the HAXSite core series of elements
• Any usage of @haxtheweb based projects, just reference, you don't need to install
• Importmaps ensure that your assets resolve correctly when pushed out and are left as bare-import references by design
• There are many reusable blocks provided to simply theme development. Check them out in the Theme Blocks section. 

Lit theme dev

The HAXCMSLitElementTheme base class provides exports for the most commonly used functions and classes when working with HAXSite based theme development. You can use your own, but Lit is highly recommended and the primarily supported / documented approach.

• HAXCMSLitElementTheme - provides all needed wiring to work with HAXEditor and HAXsite store
• unsafeCSS / html / css - lit template literal processors so you don't have to import lit
• store - HAXSite store so you don't have to reference it
• autorun / toJS - MobX common ways of interfacing with and reacting to store data

Design system alignment

While you don't have to use DDD, our design system, leveraging it's sizing, colors and spacing will help make your site feel uniform. We hope to support other design systems in the future, until then, you can leverage the hax cli again to ensure what you are developing matches our design system standards.

Just go to your site and run hax audit and it will run a job to see areas you may be able to improve in your usage of css sizing and other values to match the design system. Again, you are not required to do this, but it can help ensure things feel cohesive.

Custom theme example

This is an example of a custom theme and another for btopro internet outlet. This is only slightly different from what you get as boilerplate when starting a theme that is using the base option. You can build really complex themes as well that work with the information architecture of your site. While not providing the source, here's an example from Eberly ODL that is a HAXsite based theme.

Manual custom theme steps

The CLI is the best way to make a new theme. It puts things in place based on conventions that we have established for the project. However, you can manually engage in these steps in order to add a custom theme to an existing site. We recommend working on this locally, getting it ironed out, and then pushing it up. This example will be for a site called zombocom

1. go into zombocom via cd zombocom
2. create a new file in custom/src/ called custom-zombocom-theme.js
3. edit custom/src/custom.js and add the line import "./custom-zombocom-theme.js";
4. Use the source from btopro's internet outlet example as your starting point, renaming the class to be CustomZombocomTheme, changing the tag to custom-zombocom-theme and modifying the customElement definition at the bottom of the file to match the new class name
5. in the custom folder, run npm run start . Now changes to your theme will be updated to a 'build' version which is ready to see in your site.
6. Open a new terminal process / window, leave the other start command running.
7. To see the theme, go out of the cd ../ custom folder and edit the site.json file
8. Find the metadata.theme object (example) and modify element to be custom-zombocom-theme
9. path can be left alone as custom is already roped into the site loading routine
10. run hax site start or npm start to see your theme

Trouble shooting

If your site doesn't present the theme as is, inspect console for errors. It might also be related to needing importmap to be added to index.html (sites created as of March 3rd, 2025 do this automatically). When used for local development it should look like this:

Wrap either in a <script type="importmap"> tag.

When used in a gh-pages / vercel / netlify / surge style static publishing option where the assets are coming from a CDN, it should look like this:

If you have questions or run into issues, join us on Discord or the issue queue.