A component is a reusable UI element that consists of a `.hbs` template and an optional JavaScript class that defines its behavior. For example, someone might make a `button` in the template and handle the click behavior in the JavaScript file that shares the same name as the template. Components are broken down into two categories: - Components _without_ JavaScript, that are based only on a template. These are called Template-only or TO components. - Components _with_ JavaScript, which consist of a template and a backing class. Ember ships with two types of JavaScript classes for components: 1. Glimmer components, imported from `@glimmer/component`, which are the default component's for Ember Octane (3.15) and more recent editions. 2. Classic components, imported from `@ember/component`, which were the default for older editions of Ember (pre 3.15). Below is the documentation for Classic components. If you are looking for the API documentation for Template-only or Glimmer components, it is [available here](/ember/release/modules/@glimmer%2Fcomponent). ## Defining a Classic Component If you want to customize the component in order to handle events, transform arguments or maintain internal state, you implement a subclass of `Component`. One example is to add computed properties to your component: ```js {data-filename=app/components/person-profile.js} import Component from '@ember/component'; export default class extends Component { @computed('person.title', 'person.firstName', 'person.lastName') get displayName() { let { title, firstName, lastName } = this.person; if (title) { return `${title} ${lastName}`; } else { return `${firstName} ${lastName}`; } } } ``` And then use it in the component's template: ```handlebars {data-filename=app/templates/components/person-profile.hbs}

{{yield}} ``` ## Customizing a Classic Component's HTML Element in JavaScript ### HTML Tag The default HTML tag name used for a component's HTML representation is `div`. This can be customized by setting the `tagName` property. Consider the following component class: ```js {data-filename=app/components/emphasized-paragraph.js} import Component from '@ember/component'; export default class extends Component { tagName = 'em'; } ``` When invoked, this component would produce output that looks something like this: ```html ``` ### HTML `class` Attribute The HTML `class` attribute of a component's tag can be set by providing a `classNames` property that is set to an array of strings: ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; export default class extends Component { classNames = ['my-class', 'my-other-class']; } ``` Invoking this component will produce output that looks like this: ```html

``` `class` attribute values can also be set by providing a `classNameBindings` property set to an array of properties names for the component. The return value of these properties will be added as part of the value for the components's `class` attribute. These properties can be computed properties: ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; import { computed } from '@ember/object'; export default class extends Component { classNames = ['my-class', 'my-other-class']; classNameBindings = ['propertyA', 'propertyB']; propertyA = 'from-a'; get propertyB { if (someLogic) { return 'from-b'; } } } ``` Invoking this component will produce HTML that looks like: ```html

``` Note that `classNames` and `classNameBindings` is in addition to the `class` attribute passed with the angle bracket invocation syntax. Therefore, if this component was invoked like so: ```handlebars ``` The resulting HTML will look similar to this: ```html

``` If the value of a class name binding returns a boolean the property name itself will be used as the class name if the property is true. The class name will not be added if the value is `false` or `undefined`. ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; export default class extends Component { classNameBindings = ['hovered']; hovered = true; } ``` Invoking this component will produce HTML that looks like: ```html

``` ### Custom Class Names for Boolean Values When using boolean class name bindings you can supply a string value other than the property name for use as the `class` HTML attribute by appending the preferred value after a ":" character when defining the binding: ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; export default class extends Component { classNameBindings = ['awesome:so-very-cool']; awesome = true; } ``` Invoking this component will produce HTML that looks like: ```html

``` Boolean value class name bindings whose property names are in a camelCase-style format will be converted to a dasherized format: ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; export default class extends Component { classNameBindings = ['isUrgent']; isUrgent = true; } ``` Invoking this component will produce HTML that looks like: ```html

``` Class name bindings can also refer to object values that are found by traversing a path relative to the component itself: ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; import EmberObject from '@ember/object'; export default class extends Component { classNameBindings = ['messages.empty']; messages = EmberObject.create({ empty: true }); } ``` Invoking this component will produce HTML that looks like: ```html

``` If you want to add a class name for a property which evaluates to true and and a different class name if it evaluates to false, you can pass a binding like this: ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; export default class extends Component { classNameBindings = ['isEnabled:enabled:disabled']; isEnabled = true; } ``` Invoking this component will produce HTML that looks like: ```html

``` When isEnabled is `false`, the resulting HTML representation looks like this: ```html

``` This syntax offers the convenience to add a class if a property is `false`: ```js {data-filename=app/components/my-widget.js} import Component from '@ember/component'; // Applies no class when isEnabled is true and class 'disabled' when isEnabled is false export default class extends Component { classNameBindings = ['isEnabled::disabled']; isEnabled = true; } ``` Invoking this component when the `isEnabled` property is true will produce HTML that looks like: ```html

``` Invoking it when the `isEnabled` property on the component is `false` will produce HTML that looks like: ```html

``` Updates to the value of a class name binding will result in automatic update of the HTML `class` attribute in the component's rendered HTML representation. If the value becomes `false` or `undefined` the class name will be removed. Both `classNames` and `classNameBindings` are concatenated properties. See [EmberObject](/ember/release/classes/EmberObject) documentation for more information about concatenated properties. ### Other HTML Attributes The HTML attribute section of a component's tag can be set by providing an `attributeBindings` property set to an array of property names on the component. The return value of these properties will be used as the value of the component's HTML associated attribute: ```js {data-filename=app/components/my-anchor.js} import Component from '@ember/component'; export default class extends Component { tagName = 'a'; attributeBindings = ['href']; href = 'http://google.com'; }; ``` Invoking this component will produce HTML that looks like: ```html ``` One property can be mapped on to another by placing a ":" between the source property and the destination property: ```js {data-filename=app/components/my-anchor.js} import Component from '@ember/component'; export default class extends Component { tagName = 'a'; attributeBindings = ['url:href']; url = 'http://google.com'; }; ``` Invoking this component will produce HTML that looks like: ```html ``` HTML attributes passed with angle bracket invocations will take precedence over those specified in `attributeBindings`. Therefore, if this component was invoked like so: ```handlebars ``` The resulting HTML will looks like this: ```html ``` Note that the `href` attribute is ultimately set to `http://bing.com`, despite it having attribute binidng to the `url` property, which was set to `http://google.com`. Namespaced attributes (e.g. `xlink:href`) are supported, but have to be mapped, since `:` is not a valid character for properties in Javascript: ```js {data-filename=app/components/my-use.js} import Component from '@ember/component'; export default class extends Component { tagName = 'use'; attributeBindings = ['xlinkHref:xlink:href']; xlinkHref = '#triangle'; }; ``` Invoking this component will produce HTML that looks like: ```html ``` If the value of a property monitored by `attributeBindings` is a boolean, the attribute will be present or absent depending on the value: ```js {data-filename=app/components/my-text-input.js} import Component from '@ember/component'; export default class extends Component { tagName = 'input'; attributeBindings = ['disabled']; disabled = false; }; ``` Invoking this component will produce HTML that looks like: ```html ``` `attributeBindings` can refer to computed properties: ```js {data-filename=app/components/my-text-input.js} import Component from '@ember/component'; import { computed } from '@ember/object'; export default class extends Component { tagName = 'input'; attributeBindings = ['disabled']; get disabled() { if (someLogic) { return true; } else { return false; } } }; ``` To prevent setting an attribute altogether, use `null` or `undefined` as the value of the property used in `attributeBindings`: ```js {data-filename=app/components/my-text-input.js} import Component from '@ember/component'; export default class extends Component { tagName = 'form'; attributeBindings = ['novalidate']; novalidate = null; }; ``` Updates to the property of an attribute binding will result in automatic update of the HTML attribute in the component's HTML output. `attributeBindings` is a concatenated property. See [EmberObject](/ember/release/classes/EmberObject) documentation for more information about concatenated properties. ## Layouts The `layout` property can be used to dynamically specify a template associated with a component class, instead of relying on Ember to link together a component class and a template based on file names. In general, applications should not use this feature, but it's commonly used in addons for historical reasons. The `layout` property should be set to the default export of a template module, which is the name of a template file without the `.hbs` extension. ```handlebars {data-filename=app/templates/components/person-profile.hbs}

Person's Title

``` ```js {data-filename=app/components/person-profile.js} import Component from '@ember/component'; import layout from '../templates/components/person-profile'; export default class extends Component { layout = layout; } ``` If you invoke the component: ```handlebars

Chief Basket Weaver

Fisherman Industries

``` or ```handlebars {{#person-profile}}

Chief Basket Weaver

Fisherman Industries

{{/person-profile}} ``` It will result in the following HTML output: ```html

Person's Title

Chief Basket Weaver

Fisherman Industries

``` ## Handling Browser Events There are two ways to handle user-initiated events: ### Using the `on` modifier to capture browser events In a component's template, you can attach an event handler to any element with the `on` modifier: ```handlebars

{{this.displayName}}

Person's Title

Chief Basket Weaver

Fisherman Industries

Chief Basket Weaver

Fisherman Industries

Person's Title

Chief Basket Weaver

Fisherman Industries

Class TransformInElement private