# ember-element-helper

> Dynamic element helper for Glimmer templates.

Latest version **0.8.8** (published 2025-05-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install ember-element-helper
pnpm add ember-element-helper
yarn add ember-element-helper
bun add ember-element-helper
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: esm support; no vulnerabilities; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.8.8 |
| Published | 2025-05-12 |
| First published | 2018-10-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | 14.* \|\| 16.* \|\| >= 18 |
| Dependencies | 1 |
| Unpacked size | 26.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 44 |
| Author | Godfrey Chan |
| Maintainers | rwjblue, chancancode, ember-element-helper-github-actions |
| Keywords | ember-addon, element helper, dynamic element |

## Links

- npm: https://www.npmjs.com/package/ember-element-helper
- Repository: https://github.com/tildeio/ember-element-helper
- Homepage: https://github.com/tildeio/ember-element-helper#readme
- Issues: https://github.com/tildeio/ember-element-helper/issues
- npm.io page: https://npm.io/package/ember-element-helper

## Dependencies (1)

- [@embroider/addon-shim](https://npm.io/package/@embroider/addon-shim.md) ^1.8.3

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 0.8.8 (latest) — 2025-05-12
- 0.8.7 — 2025-04-02
- 0.8.6 — 2024-03-14
- 0.8.5 — 2023-10-11
- 0.8.4 — 2023-08-29
- 0.8.2 — 2023-08-18
- 0.7.1 — 2023-07-27
- 0.6.1 — 2022-04-14
- 0.6.0 — 2022-02-05
- 0.5.5 — 2021-06-14
- 0.5.3 — 2021-06-09
- 0.5.2 — 2021-06-09
- 0.5.0 — 2021-04-12
- 0.4.0 — 2021-03-23
- 0.3.2 — 2020-11-18
- … 4 more at https://npm.io/package/ember-element-helper/versions

## README

# ember-element-helper

[![Build Status](https://github.com/tildeio/ember-element-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/tildeio/ember-element-helper/actions/workflows/ci.yml)

Dynamic element helper for Glimmer templates.

This addon provides a ~~polyfill~~ high fidelity reference implementation of
[RFC #389](https://github.com/emberjs/rfcs/pull/389), including the proposed
amendments in [RFC PR #620](https://github.com/emberjs/rfcs/pull/620).

Please note that while [RFC #389](https://github.com/emberjs/rfcs/pull/389)
has been approved, it has not been implemented in Ember.js yet. As such, the
feature is still subject to change based on implementation feedback.

When this feature is implemented in Ember.js, we will release a 1.0 version of
this addon as a true polyfill for the feature, allowing the feature to be used
on older Ember.js versions and be completely inert on newer versions where the
official implementation is available.

## Compatibility

* Ember.js v3.28 or above
* Ember CLI v3.28 or above
* Node.js v12 or above

## Limitations

This implementation has the following known limitations:

* By default, an auto-generated `id` attribute will be added to the element
  (e.g. `id="ember123"`). It is possible to override this by providing an
  `id` attribute when invoking the component (e.g. `<Tag id="my-id" />`).
  However, it is not possible to remove the `id` attribute completely. The
  proposed helper will not have this behavior, as such this should not be
  relied upon (e.g. in CSS and `qunit-dom` selectors).

* The element will have an `ember-view` class (i.e. `class="ember-view"`).
  This is in addition and merged with the class attribute provided when
  invoking the component (e.g. `<Tag class="my-class" />` will result in
  something like `<div class="ember-view my-class" />`). It is not possible
  to remove the `ember-view` class. The proposed helper will not have this
  behavior, as such this should not be relied upon (e.g. in CSS and `qunit-dom`
  selectors).

* In Ember versions before 3.11, modifiers cannot be passed to the element,
  even when addons such as the [modifier manager](https://github.com/ember-polyfills/ember-modifier-manager-polyfill)
  and [on modifier](https://github.com/buschtoens/ember-on-modifier) polyfills
  are used. Doing so requires [RFC #435](https://github.com/emberjs/rfcs/blob/master/text/0435-modifier-splattributes.md)
  which is first available on Ember 3.11. This is an Ember.js limitation,
  unrelated to this addon.

## Installation

```
ember install ember-element-helper
```

## Usage

```hbs
{{#let (element this.tagName) as |Tag|}}
  <Tag class="my-tag">hello world!</Tag>
{{/let}}
```

You can also pass around the result of invoking this helper into any components
that accepts "contextual components" as arguments:

```hbs
<MyComponent @tag={{element "span"}} />
```

```hbs
{{!-- in my-component.hbs --}}
{{#let @tag as |Tag|}}
  <Tag class="my-tag">hello world!</Tag>
{{/let}}

{{!-- ...or more directly... --}}
<@tag class="my-tag">hello world!</@tag>
```

### Single File Components

Using the `(element)` helper with [first class component
templates](http://emberjs.github.io/rfcs/0779-first-class-component-templates.html):

```gjs
import { element } from 'ember-element-helper';

<template>
  {{#let (element @tagName) as |Tag|}}
    <Tag class="my-tag">hello world!</Tag>
  {{/let}}
</template>
```

### Glint Usage in Classic Mode

In order to use a typed `(element)` helper in classic mode, you need to import
the addon's glint template registry and extend your app's registry declaration
as described in the [Using
Addons](https://typed-ember.gitbook.io/glint/using-glint/ember/using-addons#using-glint-enabled-addons)
documentation:

```ts
import '@glint/environment-ember-loose';
import type EmberElementHelperRegistry from 'ember-element-helper/template-registry';

declare module '@glint/environment-ember-loose/registry' {
  export default interface Registry extends EmberElementHelperRegistry, /* other addon registries */ {
    // local entries
  }
}
```

> **Note:** Glint itself is still under active development, and as such breaking changes might occur.
> Therefore, Glint support by this addon is also considered experimental, and not covered by our SemVer contract!

### Typing your Components

When your component accepts an element with the `(element)` helper, you want to
give this argument a proper type. Here is how:

```ts
import type { ElementSignature } from 'ember-element-helper';

interface YourComponentSignature<T extends string> {
  Element: HTMLSectionElement;
  Args: {
    element?: ElementSignature['Return'];
  };
}
```

When the `@element` argument influences the `Element` of your component:

```ts
import type { ElementSignature, ElementFromTagName } from 'ember-element-helper';

interface YourComponentSignature<T extends string> {
  Element: ElementFromTagName<T>;
  Args: {
    element?: ElementSignature<T>['Return'];
  };
}
```

When your component already uses an element for a given condition. When
the condition isn't met, a fallback element is used. The fallback can even be
provided from the outside. Here is the type:

```ts
import type { ElementSignature, ElementFromTagName } from 'ember-element-helper';

interface YourComponentSignature<
  T extends string = 'section'
> {
  Element: HTMLButtonElement | HTMLAnchorElement | ElementFromTagName<T>;
  Args: {
    element?: ElementSignature<T>['Return'];
  };
}
```

## Contributing

See the [Contributing](CONTRIBUTING.md) guide for details.

## License

This project is licensed under the [MIT License](LICENSE.md).

---
_Source: https://npm.io/package/ember-element-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._