Contribute

Overview

HiC Showroom is open source. You can add your own HTML-in-Canvas component by opening a pull request on GitHub. Sharing your work is a great way to contribute to the community, get feedback, and inspire others.

Step 1: Fork & Clone

Fork the repository and clone it locally.

git clone https://github.com/YOUR-USERNAME/hic-showroom.git

Step 2: Create Your Component Folder

Add a new folder under components/ with your component's tag name (e.g. components/my-component/).

components/
├── my-component/
│   ├── index.js
│   ├── demo.html

Required files:

• index.js - Your web component class. Must export the class and register the custom element.
• demo.html - A standalone HTML page that showcases the effect.

Optional files:

• markup.md - You can add a markdown file that will be rendered in the Showroom next to the usage instructions. Great for providing additional context or tips for using your component.
• You can include any additional files if your component or demo needs them (style, images, extra scripts, etc.).

Step 3: Register in the Showroom

Add an entry for your component in showroom-data.js:

{
  id: 'my-component',
  name: 'My Component',
  author: 'Your Name',
}

• The id should match your component's folder name and custom element tag.

Optional properties you can add to the showroom data entry:

{
  // a brief summary of your component to show in the gallery
  description: '...',
  // an array of customization options
  customization: [
    {
      // the name of the attribute users can add to customize the effect
      attribute: 'data-speed',
      // a brief description of what the attribute controls and how to use it
      description: '...',
      // the default value for the attribute if users don't provide one
      default: '10',
    },
    {
      // more customization attributes
    }
  ],
  // the markdown file in your component folder to render in the showroom
  markdown: 'file.md',
}

Step 4: Open a Pull Request

Push your branch and open a PR against the main repository. That's it!

Notes and Tips

• Use the boilerplate as a starting point. The boilerplate.js file in the components/ folder has a clean, minimal structure that handles all the essentials: attribute transfer, content wrapping, canvas replacement, and resize observation. Start there and build your effect on top.
• Always copy host attributes to the canvas. Users will add classes, IDs, and data attributes to your component tag. Make sure they end up on the canvas so styling and customization still work after replacement.
• Set the layoutsubtree attribute on the canvas. This tells the browser that the canvas subtree is used for rendering, which is required for HTML-in-Canvas to work correctly.
• Keep the content wrapper full-size. Set width: 100% and height: 100% on the wrapper div so the user's content fills the canvas layout area.
• Handle resize properly. Use a ResizeObserver with device-pixel-content-box to keep the canvas backing store in sync with its layout size. This avoids blurry rendering on high-DPI screens.
• Guard against duplicate mounts. Use a flag like _isMounted in connectedCallback to prevent the pipeline from being set up more than once.
• Export your class. Always export the component class so it can be imported as a module. Register the custom element at the bottom with a customElements.get guard to avoid duplicate registration.
• Keep it self-contained. Your component should work with a single import — no external setup, no global state, no required build step. The simpler it is to use, the better.
• Check for API support before mounting. The HTML-in-Canvas API is experimental and not available in all browsers. Before replacing the host element, verify that the required APIs exist (e.g. gl.texElementImage2D for WebGL or ctx.drawElementImage for 2D). If the check fails, log a warning and return early so the original content stays intact.

Need Help?

If you run into any issues, have questions about the API, or just want to bounce ideas before submitting - feel free to reach out directly. I'm happy to help with anything from getting started to debugging tricky rendering issues. Don't hesitate.