Sprite & Text

Overview

These components render images, sprite sheet animations, and text onto the PixiJS stage. All sprite and text components accept standard PixiJS positioning props (x, y, scale, rotation, etc.) inherited from their underlying PIXI display objects.

<Sprite>

Renders a single static texture loaded from the asset manifest. The texture is looked up by key from stateApp.loadedAssets.

Props

key

string

required

The key used in the asset manifest (createApp({ assets })) to identify this texture. Must correspond to an asset with type: 'sprite'.

debug

boolean

When true, logs an error to the console if the texture key is not found in loadedAssets. Useful during development.

texture

PIXI.Texture

Not normally set directly on <Sprite> — the texture is resolved automatically from key. Use BaseSprite if you need to supply a texture directly.

number

Horizontal position in pixels from the parent origin. Default 0.

number

Vertical position in pixels from the parent origin. Default 0.

anchor

number | PointData

Sets the sprite’s origin/pivot. 0 = top-left, 0.5 = centre, 1 = bottom-right. Accepts a uniform number or { x, y }. Default 0.

scale

number | PointData

Uniform or per-axis scale. Default 1.

rotation

number

Rotation in radians. Default 0.

alpha

number

Opacity from 0 to 1. Default 1.

visible

boolean

Whether the sprite is rendered. Default true.

zIndex

number

Sort order within the parent container. Default 0.

tint

PIXI.ColorSource

Colour tint applied to the texture. Default 0xffffff (no tint).

isMask

boolean

Apply this sprite as an alpha mask on the parent container.

cursor

Cursor

CSS cursor string shown on hover.

Example

<Sprite
  key="logo"
  anchor={0.5}
  x={400}
  y={300}
  scale={0.8}
  alpha={0.95}
/>

<AnimatedSprite>

Renders a frame-by-frame animation from an array of textures. Wraps PIXI.AnimatedSprite.

Props

textures

PIXI.Texture[] | PIXI.FrameObject[]

required

Array of textures (or frame objects with texture and time) that form the animation frames.

play

boolean

When true, calls gotoAndPlay(0). When false, calls gotoAndStop(0). Use this to start and stop the animation declaratively. Default false.

animationSpeed

number

Playback speed multiplier. 1 = normal speed, 0.5 = half speed. Default 1.

loop

boolean

Whether the animation loops. Default true.

number

Horizontal position. Default 0.

number

Vertical position. Default 0.

anchor

number | PointData

Origin/pivot point. Default 0 (top-left).

scale

number | PointData

Uniform or per-axis scale. Default 1.

alpha

number

Opacity from 0 to 1. Default 1.

visible

boolean

Whether the sprite is rendered. Default true.

zIndex

number

Sort order within the parent. Default 0.

tint

PIXI.ColorSource

Colour tint applied to all frames. Default 0xffffff.

cursor

Cursor

CSS cursor string.

Example

<script lang="ts">
  import { getContextApp } from 'pixi-svelte';

  const { stateApp } = getContextApp();

  // Textures resolved from loadedAssets after createApp
  const frames = $derived(stateApp.loadedAssets?.['coinAnim'] as PIXI.Texture[]);
  let playing = $state(true);
</script>

<AnimatedSprite
  textures={frames ?? []}
  play={playing}
  animationSpeed={0.4}
  loop={true}
  anchor={0.5}
  x={200}
  y={300}
/>

<SpriteSheet>

A specialised <AnimatedSprite> that resolves its textures automatically from the asset manifest. Use with assets declared as type: 'spriteSheet'.

Props

key

string

required

Asset manifest key for a spriteSheet asset. The loaded texture array is passed automatically to the underlying <AnimatedSprite>.

play

boolean

Whether to play the animation. Default false.

animationSpeed

number

Playback speed multiplier. Default 1.

loop

boolean

Whether the animation loops. Default true.

number

Horizontal position. Default 0.

number

Vertical position. Default 0.

anchor

number | PointData

Origin/pivot point. Default 0.

alpha

number

Opacity from 0 to 1. Default 1.

visible

boolean

Whether the sprite is rendered. Default true.

zIndex

number

Sort order within the parent. Default 0.

cursor

Cursor

CSS cursor string.

Example

<!-- Asset manifest: coins: { type: 'spriteSheet', src: '/spritesheets/coins.json' } -->
<SpriteSheet
  key="coins"
  play={true}
  animationSpeed={0.3}
  loop={true}
  anchor={0.5}
  x={300}
  y={400}
/>

<Text>

Renders a text string using a PixiJS canvas-rendered font. Wraps PIXI.Text.

Props

text

string

The string to display.

style

PIXI.TextStyle | Partial<PIXI.TextStyleOptions>

Text styling options: font family, size, weight, colour, stroke, word wrap, alignment, etc. See the PixiJS TextStyle docs for all options.

onresize

(size: { width: number; height: number }) => void

Callback fired whenever the rendered size of the text changes — on mount and whenever text or style changes. Useful for dynamically repositioning elements relative to text bounds.

number

Horizontal position. Default 0.

number

Vertical position. Default 0.

anchor

number | PointData

Origin/pivot point. 0.5 centres the text on x/y. Default 0.

scale

number | PointData

Uniform or per-axis scale. Default 1.

alpha

number

Opacity from 0 to 1. Default 1.

visible

boolean

Whether the text is rendered. Default true.

zIndex

number

Sort order within the parent. Default 0.

cursor

Cursor

CSS cursor string.

Example

<script lang="ts">
  let balance = $state(1250.50);
</script>

<Text
  text={`Balance: $${balance.toFixed(2)}`}
  style={{
    fontFamily: 'Arial',
    fontSize: 28,
    fontWeight: 'bold',
    fill: 0xffd700,
    stroke: { color: 0x000000, width: 3 },
  }}
  anchor={0.5}
  x={400}
  y={50}
/>

<BitmapText>

Renders text using a pre-rasterised bitmap font. Faster than <Text> for frequently updated strings (scores, counters) because it does not re-rasterise on every change. Requires a font asset loaded via the manifest. <BitmapText> has the same props as <Text>. The style.fontFamily must match the name of a loaded bitmap font.

Props

text

string

The string to display.

style

PIXI.TextStyle | Partial<PIXI.TextStyleOptions>

Text style. fontFamily must match the loaded bitmap font name.

onresize

(size: { width: number; height: number }) => void

Callback fired on mount and whenever text or style changes with the current rendered dimensions.

number

Horizontal position. Default 0.

number

Vertical position. Default 0.

anchor

number | PointData

Origin/pivot point. Default 0.

alpha

number

Opacity. Default 1.

visible

boolean

Whether the text is rendered. Default true.

zIndex

number

Sort order within the parent. Default 0.

cursor

Cursor

CSS cursor string.

Example

<!-- Asset manifest: scoreFont: { type: 'font', src: '/fonts/score.fnt' } -->
<BitmapText
  text="9,999"
  style={{ fontFamily: 'ScoreFont', fontSize: 48 }}
  anchor={0.5}
  x={400}
  y={100}
/>

Use <BitmapText> over <Text> for values that update every frame (live counters, timers). Bitmap fonts are rendered once and reused, so repeated text updates are cheaper.

pixi-svelte Components

Game Utilities

Overview

<Sprite>

Props

Example

<AnimatedSprite>

Props

Example

<SpriteSheet>

Props

Example

<Text>

Props

Example

<BitmapText>

Props

Example

Build docs developers (and LLMs) love

pixi-svelte Components

Game Utilities

​Overview

​<Sprite>

​Props

​Example

​<AnimatedSprite>

​Props

​Example

​<SpriteSheet>

​Props

​Example

​<Text>

​Props

​Example

​<BitmapText>

​Props

​Example

Build docs developers (and LLMs) love

Overview

<Sprite>

Props

Example

<AnimatedSprite>

Props

Example

<SpriteSheet>

Props

Example

<Text>

Props

Example

<BitmapText>

Props

Example