Custom Elements Rails

This gem adds a simple way to automatically register custom elements in your importmap-rails app. No build step required!

• Rails support
• Installation
• Generators
• Documentation
• Contributing
• License

• Supports Rails 7.0, 7.1, 7.2 & 8.0
• Supports importmap-rails 1 and 2

Add this line to your application's Gemfile:

gem "custom_elements-rails"

Install the gem:

$ bundle install

Run the initial setup:

$ rails custom_elements:install

This will setup and edit add the following files:

app/javascript
├── application.js
└── custom_elements
    ├── hello_element.js
    └── index.js

The <app-hello> custom element can be used in views now.

You can generate a new custom element <app-demo> with rails generate custom_element demo.

The custom_elements-rails gem uses eagerDefineCustomElementsFrom to automatically register custom elements in the custom_elements folder. It parses the importmap generated by importmap-rails and registers custom elements using the customElements.define(...) API.

When defining custom elements from files, their filenames are used to generate the element names automatically. The following rules and examples clarify how file paths are converted to custom element names:

Register all files in the custom_elements folder as custom elements:

eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" });

• Filenames are transformed into kebab-case (lowercase with hyphens).
• The folder structure is reflected in the name using double hyphens (--) to separate folder names from the file name.
• A configurable prefix is added to the beginning of each custom element name.

This gem adds a generator to generate new custom elements with:

$ rails generate custom_element test 

This will generate

// app/javascript/custom_elements/test_element.js
export default class extends HTMLElement {
  constructor() {
    super()
  }

  connectedCallback() {
    console.log("test_element.js")
  }
}

which in turn will register a <app-test></app-test> custom element automatically in your app.

$ rails generate custom_element test 

To observe changes in your custom element's attributes, you need to set a static array of attribute names. The generator also supports setting those automatically:

$ rails generate custom_element test attribute1

will generate

export default class extends HTMLElement {
  static observedAttributes = ["attribute1"]

  constructor() {
    super()
  }

  connectedCallback() {
    console.log("test_element.js")
  }

  get attribute1() {
    return this.getAttribute("attribute1")
  }
}

eagerDefineCustomElementsFrom(under, options)

Currently supported optional options:

• prefix: The custom elements namespace. (default: "app")

1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with a detailed description of changes.

The gem is available as open source under the terms of the MIT License.