Skip to content

Usage

The Application component will create your PixiJS app and canvas for you.

All Vue3 Pixi elements should be children of Application.

<script setup>
import { Application } from 'vue3-pixi'
</script>

<template>
  <Application :width="240" :height="240">
    <text :anchor="0.5" :x="120" :y="120" :style="{ fill: 'white' }">
      Hello World
    </text>
  </Application>
</template>

Sprites

Sprite component requires a texture, which can be a Texture object or a path to an image.

PixiJS will load the texture in the background and show it when it’s ready - similar to how an img tag works.

<script setup>
import { Application } from 'vue3-pixi'
</script>

<template>
  <Application :width="240" :height="240">
    <sprite
      texture="/assets/food/lemonpie.png"
      :anchor="0.5"
      :x="120"
      :y="120"
    />
  </Application>
</template>

Loader

If you have a bunch of images or other resources, you may wish to show a loading screen until all images have finished loading (rather than have them pop in one after another).

Note: You may want to enable network throttling in your browser dev tools to actually see the loading screen - these are small images!

<script setup>
import { Application, Loader } from 'vue3-pixi'

const images = [
  '/assets/food/lemonpie.png',
  '/assets/food/strawberrycake.png',
  '/assets/food/cheesecake.png',
]
</script>

<template>
  <Application :width="240" :height="240">
    <Loader :resources="images">
      <!-- loading state via #fallback slot -->
      <template #fallback>
        <text :anchor="0.5" :x="120" :y="120" :style="{ fill: 'white' }">
          Loading...
        </text>
      </template>
      <!-- component with nested async dependencies -->
      <template #default="{ textures }">
        <sprite
          v-for="(image, k, i) in textures" :key="k"
          :texture="image"
          :anchor="0.5"
          :x="68 + i * 50"
          :y="120"
          :scale="1.4"
        />
      </template>
    </Loader>
  </Application>
</template>

You can have multiple Loader components as well, which could be useful if you wanted to render a fallbacks at a component-level instead.

Ticker

update loop for the application. The Application component will create one automatically, which means child components can hook into the loop with onTick.

<script lang=ts setup>
import { reactive } from 'vue'
import { onTick } from 'vue3-pixi'

const position = reactive({ x: 120, y: 120 })

let count = 0
onTick((delta) => {
  count += delta * 0.05
  position.x = 120 + Math.cos(count) * 50
  position.y = 120 + Math.sin(count) * 50
})
</script>

<template>
  <sprite
    texture="/assets/food/lemonpie.png"
    :position="position"
    :anchor="0.5"
    :scale="1.4"
  />
</template>

Filter

To use filters, you need to add the filter as a child element to the element where you want to apply the filtering effect.

<script lang="ts" setup>
import { Graphics } from 'pixi.js'

function drawRectangle(e: Graphics) {
  e.beginFill('#00a3af')
  e.drawRect(0, 0, 60, 60)
}
</script>

<template>
  <graphics :x="120" :y="60" :rotation="0.5" :pivot="0" @render="drawRectangle">
    <blur-filter :strength="2" :blur="4" />
  </graphics>
</template>

Render Events

all elements support render event, which allows for flexible manipulation of elements, For example, using on <grahpics /> and <particle-container />

This will set up a watchEffect internally that will automatically call the event handler again if any dependencies on the render method have changed.

<script lang="ts" setup>
import type { GraphicsInst } from 'vue3-pixi'

function drawArc(e: GraphicsInst) {
  e.beginFill('#4f455c')
  e.arc(0, 0, 100, 0, Math.PI, false)
}
</script>

<template>
  <graphics :x="120" :y="120" @render="drawArc" />
</template>

Accessing PixiJS Instances

You can bind PixiJS instances through ref, It is like the HTML elements, so you can bind to it if you need to access it.

<script lang="ts" setup>
import { onMounted, ref } from 'vue'
import type { TextInst } from 'vue3-pixi'

const textRef = ref<TextInst>()
onMounted(() => {
  textRef.value!.style.fill = 'yellow'
})
</script>

<template>
  <text ref="textRef" :anchor="0.5" :x="120" :y="120">
    Hello World
  </text>
</template>

Using a Custom Instance

You can add custom PIXI instances to the renderer, if you have a custom class (whether that be your own or from a third-party library).

ts
// main.js
import { Text } from 'pixi.js'
import { pathProp as defPathProp, renderer } from 'vue3-pixi'

class YellowText extends Text {
  constructor(text, style) {
    super(text, style)
    this.style.fill = 'yellow'
  }
}

renderer.use({
  name: 'YellowText',
  createElement: props => new YellowText(props.text, props.style),
  pathProp(el, key, prevValue, nextValue) {
    // handle special prop here..

    // or fallback to default
    return defPathProp(el, key, prevValue, nextValue)
  },
})
<template>
  <yellow-text text="Hello World" :anchor="0.5" :x="120" :y="120" />
</template>