Sprite & Text

Image rendering, animated sprites, and text display components

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.

x · number

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

y · 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.

x · number

Horizontal position. Default 0.

y · 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.

x · number

Horizontal position. Default 0.

y · 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.

x · number

Horizontal position. Default 0.

y · 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.

x · number

Horizontal position. Default 0.

y · 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.