Custom Elements Rails

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

Table of Contents

Click to expand

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

Rails support

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

Installation

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.

How It Works

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.

Important

Make sure your *_element.js files use export default to define the custom elements.

Naming Convention for Custom Elements

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:

Usage

Register all files in the custom_elements folder as custom elements:

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

Filepath	Generated Custom Element Name
custom_elements/demo_element.js	<app-demo>
custom_elements/demo-element.js	<app-demo>
custom_elements/foo_bar_element.js	<app-foo-bar>
custom_elements/folder/foo_bar_element.js	<app-folder--foo-bar>

Conversion Rules

• 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.

Generators

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")
  }
}

Documentation

eagerDefineCustomElementsFrom(under, options)

Currently supported optional options:

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

Contributing

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

License

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