# SpriteComponent

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

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

The SpriteComponent enables an [Entity](https://api.playcanvas.com/engine/classes/Entity.md) to render a simple static sprite or sprite
animations. The [type](https://api.playcanvas.com/engine/classes/SpriteComponent.md#type) property can be set to either [SPRITETYPE_SIMPLE](https://api.playcanvas.com/engine/variables/SPRITETYPE_SIMPLE.md) to render
a single frame from a sprite asset, or [SPRITETYPE_ANIMATED](https://api.playcanvas.com/engine/variables/SPRITETYPE_ANIMATED.md) to play one or more
[SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md)s.

You should never need to use the SpriteComponent constructor directly. To add a
SpriteComponent 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('sprite', {
    spriteAsset: spriteAsset
});
```

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

```javascript
entity.sprite.color = Color.RED; // Tint the sprite red

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

Relevant Engine API examples:

- [Animated sprite](https://playcanvas.github.io/#/misc/animated-sprite)

## Accessors

### autoPlayClip

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

Gets the name of the clip to play automatically when the component is enabled.

### batchGroupId

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

Gets the batch group for the sprite.

### clips

```ts
get clips(): {}
set clips(value: {})
```

Gets the dictionary that contains [SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md)s.

### color

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

Gets the color tint of the sprite in sRGB color space. Use the setter to update the tint.

### currentClip

```ts
get currentClip(): SpriteAnimationClip
```

Gets the current clip being played.

### drawOrder

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

Gets the draw order of the component.

### flipX

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

Gets whether to flip the X axis when rendering a sprite.

### flipY

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

Gets whether to flip the Y axis when rendering a sprite.

### frame

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

Gets which frame from the current sprite asset to render.

### height

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

Gets the height of the sprite when rendering using 9-Slicing.

### 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 sprite belongs.

### opacity

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

Gets the opacity of the sprite.

### speed

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

Gets the global speed modifier used when playing sprite animation clips.

### sprite

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

Gets the current sprite.

### spriteAsset

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

Gets the asset id or the [Asset](https://api.playcanvas.com/engine/classes/Asset.md) of the sprite to render.

### type

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

Gets the type of the SpriteComponent.

### width

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

Gets the width of the sprite when rendering using 9-Slicing.

## Methods

### addClip

```ts
addClip(data: object): SpriteAnimationClip
```

Creates and adds a new [SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md) to the component's clips.

**Parameters**

- `data` (`object`): Data for the new animation clip.
    - `data.fps` (`number`, optional): Frames per second for the animation clip.
    - `data.loop` (`boolean`, optional): Whether to loop the animation clip.
    - `data.name` (`string`, optional): The name of the new animation clip.
    - `data.spriteAsset` (`number |` [`Asset`](https://api.playcanvas.com/engine/classes/Asset.md)`<string>`, optional): The asset id or
      the [Asset](https://api.playcanvas.com/engine/classes/Asset.md) of the sprite that this clip will play.

**Returns** [`SpriteAnimationClip`](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md): The new clip that was added.

### clip

```ts
clip(name: string): SpriteAnimationClip
```

Get an animation clip by name.

**Parameters**

- `name` (`string`): The name of the clip.

**Returns** [`SpriteAnimationClip`](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md): The clip.

### pause

```ts
pause(): void
```

Pauses the current animation clip.

### play

```ts
play(name: string): SpriteAnimationClip
```

Plays a sprite animation clip by name. If the animation clip is already playing then this
will do nothing.

**Parameters**

- `name` (`string`): The name of the clip to play.

**Returns** [`SpriteAnimationClip`](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md): The clip that started playing.

### removeClip

```ts
removeClip(name: string): void
```

Removes a clip by name.

**Parameters**

- `name` (`string`): The name of the animation clip to remove.

### resume

```ts
resume(): void
```

Resumes the current paused animation clip.

### stop

```ts
stop(): void
```

Stops the current animation clip and resets it to the first frame.

## Events

### EVENT_END

```ts
static EVENT_END: string = 'end'
```

Fired when an animation clip stops playing because it reached its end. The handler is passed
the [SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md) that ended.

**Example**

```ts
entity.sprite.on('end', (clip) => {
    console.log(`Animation clip ${clip.name} ended.`);
});
```

### EVENT_LOOP

```ts
static EVENT_LOOP: string = 'loop'
```

Fired when an animation clip reached the end of its current loop. The handler is passed the
[SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md) that looped.

**Example**

```ts
entity.sprite.on('loop', (clip) => {
    console.log(`Animation clip ${clip.name} looped.`);
});
```

### EVENT_PAUSE

```ts
static EVENT_PAUSE: string = 'pause'
```

Fired when an animation clip is paused. The handler is passed the
[SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md) that was paused.

**Example**

```ts
entity.sprite.on('pause', (clip) => {
    console.log(`Animation clip ${clip.name} paused.`);
});
```

### EVENT_PLAY

```ts
static EVENT_PLAY: string = 'play'
```

Fired when an animation clip starts playing. The handler is passed the
[SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md) that started playing.

**Example**

```ts
entity.sprite.on('play', (clip) => {
    console.log(`Animation clip ${clip.name} started playing.`);
});
```

### EVENT_RESUME

```ts
static EVENT_RESUME: string = 'resume'
```

Fired when an animation clip is resumed. The handler is passed the
[SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md) that was resumed.

**Example**

```ts
entity.sprite.on('resume', (clip) => {
    console.log(`Animation clip ${clip.name} resumed.`);
});
```

### EVENT_STOP

```ts
static EVENT_STOP: string = 'stop'
```

Fired when an animation clip is stopped. The handler is passed the
[SpriteAnimationClip](https://api.playcanvas.com/engine/classes/SpriteAnimationClip.md) that was stopped.

**Example**

```ts
entity.sprite.on('stop', (clip) => {
    console.log(`Animation clip ${clip.name} stopped.`);
});
```

## 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`