# ButtonComponent

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

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/framework/components/button/component.js#L82

The ButtonComponent enables an [Entity](https://api.playcanvas.com/engine/classes/Entity.md) to behave like a button, with different visual
states for hover and press interactions. It is designed to be used together with an
[ElementComponent](https://api.playcanvas.com/engine/classes/ElementComponent.md) on the same entity, which provides the button's visual appearance and
input hit area. Set [imageEntity](https://api.playcanvas.com/engine/classes/ButtonComponent.md#imageentity), usually to the button's own entity, to choose the
element that is tinted, or has its sprite changed, for each visual state.

You should never need to use the ButtonComponent constructor directly. To add a
ButtonComponent 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', {
    type: ELEMENTTYPE_IMAGE,
    useInput: true
});
entity.addComponent('button', {
    imageEntity: entity
});
```

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

```javascript
entity.button.hoverTint = Color.YELLOW; // Set the hover tint color

console.log(entity.button.hoverTint);      // Get the hover tint color and print it
```

Relevant Engine API examples:

- [Buttons](https://playcanvas.github.io/#/user-interface/buttons)
- [Toggles and radio groups](https://playcanvas.github.io/#/user-interface/common-widgets)

## Accessors

### active

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

Gets the button's active state.

### fadeDuration

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

Gets the duration to be used when fading between tints, in milliseconds.

### hitPadding

```ts
get hitPadding(): Vec4
set hitPadding(arg: Vec4)
```

Gets the padding to be used in hit-test calculations.

### hoverSpriteAsset

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

Gets the sprite to be used as the button image when the user hovers over it.

### hoverSpriteFrame

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

Gets the frame to be used from the hover sprite.

### hoverTint

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

Gets the tint color to be used on the button image when the user hovers over it.

### imageEntity

```ts
get imageEntity(): Entity | null
set imageEntity(arg: Entity | null)
```

Gets the entity to be used as the button background.

### inactiveSpriteAsset

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

Gets the sprite to be used as the button image when the button is not interactive.

### inactiveSpriteFrame

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

Gets the frame to be used from the inactive sprite.

### inactiveTint

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

Gets the tint color to be used on the button image when the button is not interactive.

### pressedSpriteAsset

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

Gets the sprite to be used as the button image when the user presses it.

### pressedSpriteFrame

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

Gets the frame to be used from the pressed sprite.

### pressedTint

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

Gets the tint color to be used on the button image when the user presses it.

### transitionMode

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

Gets the button transition mode.

## Events

### EVENT_CLICK

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

Fired when the mouse is pressed and released on the component or when a touch starts and ends on
the component. The handler is passed a [ElementMouseEvent](https://api.playcanvas.com/engine/classes/ElementMouseEvent.md) or [ElementTouchEvent](https://api.playcanvas.com/engine/classes/ElementTouchEvent.md).

**Example**

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

### EVENT_HOVEREND

```ts
static EVENT_HOVEREND: string = 'hoverend'
```

Fired when the button changes state to be not hovered.

**Example**

```ts
entity.button.on('hoverend', () => {
    console.log(`Entity ${entity.name} unhovered`);
});
```

### EVENT_HOVERSTART

```ts
static EVENT_HOVERSTART: string = 'hoverstart'
```

Fired when the button changes state to be hovered.

**Example**

```ts
entity.button.on('hoverstart', () => {
    console.log(`Entity ${entity.name} hovered`);
});
```

### EVENT_MOUSEDOWN

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

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

**Example**

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

### EVENT_MOUSEENTER

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

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

**Example**

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

### EVENT_MOUSELEAVE

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

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

**Example**

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

### EVENT_MOUSEUP

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

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

**Example**

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

### EVENT_PRESSEDEND

```ts
static EVENT_PRESSEDEND: string = 'pressedend'
```

Fired when the button changes state to be not pressed.

**Example**

```ts
entity.button.on('pressedend', () => {
    console.log(`Entity ${entity.name} unpressed`);
});
```

### EVENT_PRESSEDSTART

```ts
static EVENT_PRESSEDSTART: string = 'pressedstart'
```

Fired when the button changes state to be pressed.

**Example**

```ts
entity.button.on('pressedstart', () => {
    console.log(`Entity ${entity.name} pressed`);
});
```

### EVENT_SELECTEND

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

Fired when a xr select ends on the component. The handler is passed a
[ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

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

### EVENT_SELECTENTER

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

Fired when a xr select now hovering over the component. The handler is passed a
[ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

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

### EVENT_SELECTLEAVE

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

Fired when a xr select not hovering over the component. The handler is passed a
[ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

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

### EVENT_SELECTSTART

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

Fired when a xr select starts on the component. The handler is passed a
[ElementSelectEvent](https://api.playcanvas.com/engine/classes/ElementSelectEvent.md).

**Example**

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

### EVENT_TOUCHCANCEL

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

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

**Example**

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

### EVENT_TOUCHEND

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

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

**Example**

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

### EVENT_TOUCHLEAVE

```ts
static EVENT_TOUCHLEAVE: string = 'touchleave'
```

Fired when a touch leaves the component. The handler is passed a [ElementTouchEvent](https://api.playcanvas.com/engine/classes/ElementTouchEvent.md).

**Example**

```ts
entity.button.on('touchleave', (event) => {
    console.log(`Touch left entity ${entity.name}`);
});
```

### EVENT_TOUCHSTART

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

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

**Example**

```ts
entity.button.on('touchstart', (event) => {
    console.log(`Touch started 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`