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 Component.extend({ displayName: computed('person.title', 'person.firstName', 'person.lastName', function() { 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ classNames: ['my-class', 'my-other-class'], classNameBindings: ['propertyA', 'propertyB'], propertyA: 'from-a', propertyB: computed(function() { 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ 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 Component.extend({ tagName: 'input', attributeBindings: ['disabled'], disabled: computed(function() { 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 Component.extend({ 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 Component.extend({ 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 TransformActionSyntax private