# ElementComponent

Class · extends [`Component`](https://api.playcanvas.com/engine/classes/Component.md) · category: User Interface

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/components/element/component.js#L100

ElementComponents are used to construct user interfaces. The [type](https://api.playcanvas.com/engine/classes/ElementComponent.md#type) property can be
configured in 3 main ways: as a text element, as an image element or as a group element. If
the ElementComponent has a [ScreenComponent](https://api.playcanvas.com/engine/classes/ScreenComponent.md) ancestor in the hierarchy, it
will be transformed with respect to the coordinate system of the screen. If there is no
[ScreenComponent](https://api.playcanvas.com/engine/classes/ScreenComponent.md) ancestor, the ElementComponent will be transformed like any other
entity.

You should never need to use the ElementComponent constructor directly. To add an
ElementComponent to an [Entity](https://api.playcanvas.com/engine/classes/Entity.md), use [Entity#addComponent](https://api.playcanvas.com/engine/classes/Entity.md#addcomponent):

```javascript
const entity = new Entity();
entity.addComponent('element'); // This defaults to a 'group' element
```

To create a simple text-based element:

```javascript
entity.addComponent('element', {
    anchor: new Vec4(0.5, 0.5, 0.5, 0.5), // centered anchor
    fontAsset: fontAsset,
    fontSize: 128,
    pivot: new Vec2(0.5, 0.5),            // centered pivot
    text: 'Hello World!',
    type: ELEMENTTYPE_TEXT
});
```

Once the ElementComponent is added to the entity, you can access it via the
[Entity#element](https://api.playcanvas.com/engine/classes/Entity.md#element) property:

```javascript
entity.element.color = Color.RED; // Set the element's color to red

console.log(entity.element.color);   // Get the element's color and print it
```

Relevant Engine API examples:

- [Anchors](https://playcanvas.github.io/#/user-interface/anchors)
- [Image fitting](https://playcanvas.github.io/#/user-interface/image-fit)
- [Sliced panels](https://playcanvas.github.io/#/user-interface/panel)
- [Masking](https://playcanvas.github.io/#/user-interface/masking)
- [Rendering 3D into an image](https://playcanvas.github.io/#/user-interface/render-to-image)
- [Custom shader](https://playcanvas.github.io/#/user-interface/custom-shader)
- [Basic text rendering](https://playcanvas.github.io/#/user-interface/text)
- [Auto font sizing](https://playcanvas.github.io/#/user-interface/text-auto-font-size)
- [Emojis](https://playcanvas.github.io/#/user-interface/text-emojis)
- [Justified text](https://playcanvas.github.io/#/user-interface/text-justify)
- [Text localization](https://playcanvas.github.io/#/user-interface/text-localization)
- [Text markup](https://playcanvas.github.io/#/user-interface/text-markup)
- [Typewriter text](https://playcanvas.github.io/#/user-interface/text-typewriter)

## Properties

### screen

```ts
screen: Entity | null
```

The Entity with a [ScreenComponent](https://api.playcanvas.com/engine/classes/ScreenComponent.md) that this component belongs to. This is
automatically set when the component is a child of a ScreenComponent.

## Accessors

### aabb

```ts
get aabb(): BoundingBox | null
```

Gets the world space axis-aligned bounding box for this element component.

### alignment

```ts
get alignment(): Vec2
set alignment(arg: Vec2)
```

Gets the horizontal and vertical alignment of the text.

### anchor

```ts
get anchor(): Readonly<Vec4>
set anchor(value: Readonly<Vec4>)
```

Gets the anchor for this element component. Use the setter to update the anchor.

### autoFitHeight

```ts
get autoFitHeight(): boolean
set autoFitHeight(arg: boolean)
```

Gets whether the font size and line height will scale so that the text fits inside the
height of the Element.

### autoFitWidth

```ts
get autoFitWidth(): boolean
set autoFitWidth(arg: boolean)
```

Gets whether the font size and line height will scale so that the text fits inside the width
of the Element.

### autoHeight

```ts
get autoHeight(): boolean
set autoHeight(arg: boolean)
```

Gets whether to automatically set the height of the component to be the same as the
[textHeight](https://api.playcanvas.com/engine/classes/ElementComponent.md#textheight).

### autoWidth

```ts
get autoWidth(): boolean
set autoWidth(arg: boolean)
```

Gets whether to automatically set the width of the component to be the same as the
[textWidth](https://api.playcanvas.com/engine/classes/ElementComponent.md#textwidth).

### batchGroupId

```ts
get batchGroupId(): number
set batchGroupId(value: number)
```

Gets the batch group (see [BatchGroup](https://api.playcanvas.com/engine/classes/BatchGroup.md)) for this element.

### bottom

```ts
get bottom(): number
set bottom(value: number)
```

Gets the distance from the bottom edge of the anchor.

### calculatedHeight

```ts
get calculatedHeight(): number
set calculatedHeight(value: number)
```

Gets the height at which the element will be rendered.

### calculatedWidth

```ts
get calculatedWidth(): number
set calculatedWidth(value: number)
```

Gets the width at which the element will be rendered.

### canvasCorners

```ts
get canvasCorners(): Vec2[]
```

Gets the array of 4 [Vec2](https://api.playcanvas.com/engine/classes/Vec2.md)s that represent the bottom left, bottom right, top right
and top left corners of the component in canvas pixels. Only works for screen space element
components.

### color

```ts
get color(): Readonly<Color>
set color(arg: Readonly<Color>)
```

Gets the color of the element. Use the setter to update the color.

### drawOrder

```ts
get drawOrder(): number
set drawOrder(value: number)
```

Gets the draw order of the component.

### enableMarkup

```ts
get enableMarkup(): boolean
set enableMarkup(arg: boolean)
```

Gets whether markup processing is enabled for this element.

### fitMode

```ts
get fitMode(): string
set fitMode(value: string)
```

Gets the fit mode of the element.

### font

```ts
get font(): Font | CanvasFont
set font(arg: Font | CanvasFont)
```

Gets the font used for rendering the text.

### fontAsset

```ts
get fontAsset(): number | Asset<string> | null
set fontAsset(arg: number | Asset<string> | null)
```

Gets the id of the font asset used for rendering the text.

### fontSize

```ts
get fontSize(): number
set fontSize(arg: number)
```

Gets the size of the font.

### height

```ts
get height(): number
set height(value: number)
```

Gets the height of the element.

### justify

```ts
get justify(): boolean
set justify(arg: boolean)
```

Gets whether wrapped lines are stretched to be flush with both edges of the element.

### key

```ts
get key(): string
set key(arg: string)
```

Gets the localization key to use to get the localized text from [Application#i18n](https://api.playcanvas.com/engine/classes/Application.md#i18n).

### layers

```ts
get layers(): readonly number[]
set layers(value: readonly number[])
```

Gets the array of layer IDs ([Layer#id](https://api.playcanvas.com/engine/classes/Layer.md#id)) to which this element belongs.

### left

```ts
get left(): number
set left(value: number)
```

Gets the distance from the left edge of the anchor.

### lineHeight

```ts
get lineHeight(): number
set lineHeight(arg: number)
```

Gets the height of each line of text.

### lines

```ts
get lines(): string[]
```

Gets the lines of rendered text, split by line breaks and word wrapping. Only works for
[ELEMENTTYPE_TEXT](https://api.playcanvas.com/engine/variables/ELEMENTTYPE_TEXT.md) elements, and is populated when the text is laid out, so it reads as
`undefined` until the first update.

### margin

```ts
get margin(): Readonly<Vec4>
set margin(value: Readonly<Vec4>)
```

Gets the distance from the left, bottom, right and top edges of the anchor. Use the setter to
update the margin.

### mask

```ts
get mask(): boolean
set mask(arg: boolean)
```

Gets whether the Image Element should be treated as a mask.

### material

```ts
get material(): Material
set material(arg: Material)
```

Gets the material to use when rendering an image.

### materialAsset

```ts
get materialAsset(): number | Asset<string> | null
set materialAsset(arg: number | Asset<string> | null)
```

Gets the id of the material asset to use when rendering an image.

### maxFontSize

```ts
get maxFontSize(): number
set maxFontSize(arg: number)
```

Gets the maximum size that the font can scale to when [autoFitWidth](https://api.playcanvas.com/engine/classes/ElementComponent.md#autofitwidth) or
[autoFitHeight](https://api.playcanvas.com/engine/classes/ElementComponent.md#autofitheight) are true.

### maxLines

```ts
get maxLines(): number | null
set maxLines(arg: number | null)
```

Gets the maximum number of lines that the Element can wrap to. Returns -1 if there is no
limit.

### minFontSize

```ts
get minFontSize(): number
set minFontSize(arg: number)
```

Gets the minimum size that the font can scale to when [autoFitWidth](https://api.playcanvas.com/engine/classes/ElementComponent.md#autofitwidth) or
[autoFitHeight](https://api.playcanvas.com/engine/classes/ElementComponent.md#autofitheight) are true.

### opacity

```ts
get opacity(): number
set opacity(arg: number)
```

Gets the opacity of the element.

### outlineColor

```ts
get outlineColor(): Color
set outlineColor(arg: Color)
```

Gets the text outline effect color and opacity.

### outlineThickness

```ts
get outlineThickness(): number
set outlineThickness(arg: number)
```

Gets the width of the text outline effect.

### pivot

```ts
get pivot(): Readonly<Vec2>
set pivot(value: Readonly<Vec2>)
```

Gets the position of the pivot of the component relative to its anchor. Use the setter to
update the pivot.

### pixelsPerUnit

```ts
get pixelsPerUnit(): number | null
set pixelsPerUnit(arg: number | null)
```

Gets the number of pixels that map to one PlayCanvas unit.

### rangeEnd

```ts
get rangeEnd(): number
set rangeEnd(arg: number)
```

Gets the index of the last character to render.

### rangeStart

```ts
get rangeStart(): number
set rangeStart(arg: number)
```

Gets the index of the first character to render.

### rect

```ts
get rect(): Readonly<Vec4> | null
set rect(arg: Readonly<Vec4> | null)
```

Gets the region of the texture to use in order to render an image. Use the setter to update
the region.

### right

```ts
get right(): number
set right(value: number)
```

Gets the distance from the right edge of the anchor.

### rtlReorder

```ts
get rtlReorder(): boolean
set rtlReorder(arg: boolean)
```

Gets whether to reorder the text for RTL languages.

### screenCorners

```ts
get screenCorners(): Vec3[]
```

Gets the array of 4 [Vec3](https://api.playcanvas.com/engine/classes/Vec3.md)s that represent the bottom left, bottom right, top right
and top left corners of the component relative to its parent [ScreenComponent](https://api.playcanvas.com/engine/classes/ScreenComponent.md).

### shadowColor

```ts
get shadowColor(): Color
set shadowColor(arg: Color)
```

Gets the text shadow effect color and opacity.

### shadowOffset

```ts
get shadowOffset(): Vec2
set shadowOffset(arg: Vec2)
```

Gets the offset of the text shadow, relative to the text.

### spacing

```ts
get spacing(): number
set spacing(arg: number)
```

Gets the spacing between the letters of the text.

### sprite

```ts
get sprite(): Sprite
set sprite(arg: Sprite)
```

Gets the sprite to render.

### spriteAsset

```ts
get spriteAsset(): number | Asset<string> | null
set spriteAsset(arg: number | Asset<string> | null)
```

Gets the id of the sprite asset to render.

### spriteFrame

```ts
get spriteFrame(): number
set spriteFrame(arg: number)
```

Gets the frame of the sprite to render.

### text

```ts
get text(): string
set text(arg: string)
```

Gets the text to render.

### textHeight

```ts
get textHeight(): number
```

Gets the height of the text rendered by the component. Only works for
[ELEMENTTYPE_TEXT](https://api.playcanvas.com/engine/variables/ELEMENTTYPE_TEXT.md) elements.

### texture

```ts
get texture(): Texture
set texture(arg: Texture)
```

Gets the texture to render.

### textureAsset

```ts
get textureAsset(): number | Asset<string> | null
set textureAsset(arg: number | Asset<string> | null)
```

Gets the id of the texture asset to render.

### textWidth

```ts
get textWidth(): number
```

Gets the width of the text rendered by the component. Only works for
[ELEMENTTYPE_TEXT](https://api.playcanvas.com/engine/variables/ELEMENTTYPE_TEXT.md) elements.

### top

```ts
get top(): number
set top(value: number)
```

Gets the distance from the top edge of the anchor.

### type

```ts
get type(): string
set type(value: string)
```

Gets the type of the ElementComponent.

### unicodeConverter

```ts
get unicodeConverter(): boolean
set unicodeConverter(arg: boolean)
```

Gets whether to convert unicode characters.

### useInput

```ts
get useInput(): boolean
set useInput(value: boolean)
```

Gets whether the component will receive mouse and touch input events.

### width

```ts
get width(): number
set width(value: number)
```

Gets the width of the element.

### worldCorners

```ts
get worldCorners(): Vec3[]
```

Gets the array of 4 [Vec3](https://api.playcanvas.com/engine/classes/Vec3.md)s that represent the bottom left, bottom right, top right
and top left corners of the component in world space. Only works for 3D element components.

### wrapLines

```ts
get wrapLines(): boolean
set wrapLines(arg: boolean)
```

Gets whether to automatically wrap lines based on the element width.

## Events

### EVENT_CLICK

```ts
static EVENT_CLICK: string = 'click'
```

Fired when the mouse is pressed and released on the component, when a touch starts and ends
on the component, or when an XR input source starts and ends a select action on the
component. Only fired when useInput is true. The handler is passed an
[ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md), [ElementTouchEvent](https://api.playcanvas.com/engine/classes/ElementTouchEvent.md) or [ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

```ts
entity.element.on('click', (event) => {
    console.log(`Click event on entity ${entity.name}`);
});
```

### EVENT_MOUSEDOWN

```ts
static EVENT_MOUSEDOWN: string = 'mousedown'
```

Fired when the mouse is pressed while the cursor is on the component. Only fired when
useInput is true. The handler is passed an [ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md).

**Example**

```ts
entity.element.on('mousedown', (event) => {
    console.log(`Mouse down event on entity ${entity.name}`);
});
```

### EVENT_MOUSEENTER

```ts
static EVENT_MOUSEENTER: string = 'mouseenter'
```

Fired when the mouse cursor enters the component. Only fired when useInput is true. The
handler is passed an [ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md).

**Example**

```ts
entity.element.on('mouseenter', (event) => {
    console.log(`Mouse enter event on entity ${entity.name}`);
});
```

### EVENT_MOUSELEAVE

```ts
static EVENT_MOUSELEAVE: string = 'mouseleave'
```

Fired when the mouse cursor leaves the component. Only fired when useInput is true. The
handler is passed an [ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md).

**Example**

```ts
entity.element.on('mouseleave', (event) => {
    console.log(`Mouse leave event on entity ${entity.name}`);
});
```

### EVENT_MOUSEMOVE

```ts
static EVENT_MOUSEMOVE: string = 'mousemove'
```

Fired when the mouse cursor is moved on the component. Only fired when useInput is true. The
handler is passed an [ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md).

**Example**

```ts
entity.element.on('mousemove', (event) => {
    console.log(`Mouse move event on entity ${entity.name}`);
});
```

### EVENT_MOUSEUP

```ts
static EVENT_MOUSEUP: string = 'mouseup'
```

Fired when the mouse is released while the cursor is on the component. Only fired when
useInput is true. The handler is passed an [ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md).

**Example**

```ts
entity.element.on('mouseup', (event) => {
    console.log(`Mouse up event on entity ${entity.name}`);
});
```

### EVENT_MOUSEWHEEL

```ts
static EVENT_MOUSEWHEEL: string = 'mousewheel'
```

Fired when the mouse wheel is scrolled on the component. Only fired when useInput is true.
The handler is passed an [ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md).

**Example**

```ts
entity.element.on('mousewheel', (event) => {
    console.log(`Mouse wheel event on entity ${entity.name}`);
});
```

### EVENT_SELECTEND

```ts
static EVENT_SELECTEND: string = 'selectend'
```

Fired when an XR input source ends a select action that started on the component, even if
its ray no longer points at the component. Only fired when useInput is true. The handler is
passed an [ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

```ts
entity.element.on('selectend', (event) => {
    console.log(`Select end event on entity ${entity.name}`);
});
```

### EVENT_SELECTENTER

```ts
static EVENT_SELECTENTER: string = 'selectenter'
```

Fired when the ray of an XR input source starts pointing at the component. Only fired when
useInput is true and the input source's [XrInputSource#elementInput](https://api.playcanvas.com/engine/classes/XrInputSource.md#elementinput) is true. The
handler is passed an [ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

```ts
entity.element.on('selectenter', (event) => {
    console.log(`Select enter event on entity ${entity.name}`);
});
```

### EVENT_SELECTLEAVE

```ts
static EVENT_SELECTLEAVE: string = 'selectleave'
```

Fired when the ray of an XR input source stops pointing at the component, or when the input
source is removed while its ray points at the component. Only fired when useInput is true.
The handler is passed an [ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

```ts
entity.element.on('selectleave', (event) => {
    console.log(`Select leave event on entity ${entity.name}`);
});
```

### EVENT_SELECTMOVE

```ts
static EVENT_SELECTMOVE: string = 'selectmove'
```

Fired every XR frame while an XR input source holds a select action that started on the
component, even if its ray no longer points at the component. Only fired when useInput is
true. The handler is passed an [ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

```ts
entity.element.on('selectmove', (event) => {
    console.log(`Select move event on entity ${entity.name}`);
});
```

### EVENT_SELECTSTART

```ts
static EVENT_SELECTSTART: string = 'selectstart'
```

Fired when an XR input source starts a select action, such as pulling a controller trigger
or pinching, while its ray points at the component. Only fired when useInput is true and
the input source's [XrInputSource#elementInput](https://api.playcanvas.com/engine/classes/XrInputSource.md#elementinput) is true. The handler is passed an
[ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

```ts
entity.element.on('selectstart', (event) => {
    console.log(`Select start event on entity ${entity.name}`);
});
```

### EVENT_TOUCHCANCEL

```ts
static EVENT_TOUCHCANCEL: string = 'touchcancel'
```

Fired when a touch is canceled on the component. Only fired when useInput is true. The
handler is passed an [ElementTouchEvent](https://api.playcanvas.com/engine/classes/ElementTouchEvent.md).

**Example**

```ts
entity.element.on('touchcancel', (event) => {
    console.log(`Touch cancel event on entity ${entity.name}`);
});
```

### EVENT_TOUCHEND

```ts
static EVENT_TOUCHEND: string = 'touchend'
```

Fired when a touch ends on the component. Only fired when useInput is true. The handler is
passed an [ElementTouchEvent](https://api.playcanvas.com/engine/classes/ElementTouchEvent.md).

**Example**

```ts
entity.element.on('touchend', (event) => {
    console.log(`Touch end event on entity ${entity.name}`);
});
```

### EVENT_TOUCHMOVE

```ts
static EVENT_TOUCHMOVE: string = 'touchmove'
```

Fired when a touch moves after it started touching the component. Only fired when useInput
is true. The handler is passed an [ElementTouchEvent](https://api.playcanvas.com/engine/classes/ElementTouchEvent.md).

**Example**

```ts
entity.element.on('touchmove', (event) => {
    console.log(`Touch move event on entity ${entity.name}`);
});
```

### EVENT_TOUCHSTART

```ts
static EVENT_TOUCHSTART: string = 'touchstart'
```

Fired when a touch starts on the component. Only fired when useInput is true. The handler is
passed an [ElementTouchEvent](https://api.playcanvas.com/engine/classes/ElementTouchEvent.md).

**Example**

```ts
entity.element.on('touchstart', (event) => {
    console.log(`Touch start event on entity ${entity.name}`);
});
```

## Inherited from [Component](https://api.playcanvas.com/engine/classes/Component.md)

- `entity: Entity`
- `system: ComponentSystem`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`