Skip to content
SveltePixi

Container

Renders a PIXI.Container. It is the basis for most SveltePixi components in the same way that most PIXI objects extend PIXI.Container.

When child components are rendered inside, their coordinates become local to the parent Container.

PIXI.Container description from PixiJS source

Container is a general-purpose display object that holds children. It also adds built-in support for advanced rendering features like masking and filtering.

It is the base class of all display objects that act as a container for other objects, including Graphics and Sprite.

Transforms

The [transform]{@link scene.Container#transform} of a display object describes the projection from its local coordinate space to its parent's local coordinate space. The following properties are derived from the transform:

Property Description
[pivot]{@link scene.Container#pivot} Invariant under rotation, scaling, and skewing. The projection of into the parent's space of the pivot is equal to position, regardless of the other three transformations. In other words, It is the center of rotation, scaling, and skewing.
[position]{@link scene.Container#position} Translation. This is the position of the [pivot]{@link scene.Container#pivot} in the parent's local space. The default value of the pivot is the origin (0,0). If the top-left corner of your display object is (0,0) in its local space, then the position will be its top-left corner in the parent's local space.
[scale]{@link scene.Container#scale} Scaling. This will stretch (or compress) the display object's projection. The scale factors are along the local coordinate axes. In other words, the display object is scaled before rotated or skewed. The center of scaling is the [pivot]{@link scene.Container#pivot}.
[rotation]{@link scene.Container#rotation} Rotation. This will rotate the display object's projection by this angle (in radians).
[skew]{@link scene.Container#skew}

Skewing. This can be used to deform a rectangular display object into a parallelogram.

In PixiJS, skew has a slightly different behaviour than the conventional meaning. It can be thought of the net rotation applied to the coordinate axes (separately). For example, if "skew.x" is ⍺ and "skew.y" is β, then the line x = 0 will be rotated by ⍺ (y = -x*cot⍺) and the line y = 0 will be rotated by β (y = x*tanβ). A line y = x*tanϴ (i.e. a line at angle ϴ to the x-axis in local-space) will be rotated by an angle between ⍺ and β.

It can be observed that if skew is applied equally to both axes, then it will be equivalent to applying a rotation. Indeed, if "skew.x" = -ϴ and "skew.y" = ϴ, it will produce an equivalent of "rotation" = ϴ.

Another quite interesting observation is that "skew.x", "skew.y", rotation are commutative operations. Indeed, because rotation is essentially a careful combination of the two.

[angle]{@link scene.Container#angle} Rotation. This is an alias for [rotation]{@link scene.Container#rotation}, but in degrees.
[x]{@link scene.Container#x} Translation. This is an alias for position.x!
[y]{@link scene.Container#y} Translation. This is an alias for position.y!
[width]{@link scene.Container#width} Implemented in [Container]{@link scene.Container}. Scaling. The width property calculates scale.x by dividing the "requested" width by the local bounding box width. It is indirectly an abstraction over scale.x, and there is no concept of user-defined width.
[height]{@link scene.Container#height} Implemented in [Container]{@link scene.Container}. Scaling. The height property calculates scale.y by dividing the "requested" height by the local bounding box height. It is indirectly an abstraction over scale.y, and there is no concept of user-defined height.
Alpha

This alpha sets a display object's relative opacity w.r.t its parent. For example, if the alpha of a display object is 0.5 and its parent's alpha is 0.5, then it will be rendered with 25% opacity (assuming alpha is not applied on any ancestor further up the chain).

Renderable vs Visible

The renderable and visible properties can be used to prevent a display object from being rendered to the screen. However, there is a subtle difference between the two. When using renderable, the transforms of the display object (and its children subtree) will continue to be calculated. When using visible, the transforms will not be calculated.

import { BlurFilter, Container, Graphics, Sprite } from 'pixi.js';

const container = new Container();
const sprite = Sprite.from('https://s3-us-west-2.amazonaws.com/s.cdpn.io/693612/IaUrttj.png');

sprite.width = 512;
sprite.height = 512;

// Adds a sprite as a child to this container. As a result, the sprite will be rendered whenever the container
// is rendered.
container.addChild(sprite);

// Blurs whatever is rendered by the container
container.filters = [new BlurFilter()];

// Only the contents within a circle at the center should be rendered onto the screen.
container.mask = new Graphics()
    .beginFill(0xffffff)
    .drawCircle(sprite.width / 2, sprite.height / 2, Math.min(sprite.width, sprite.height) / 2)
    .endFill();
RenderGroup

In PixiJS v8, containers can be set to operate in 'render group mode', transforming them into entities akin to a stage in traditional rendering paradigms. A render group is a root renderable entity, similar to a container, but it's rendered in a separate pass with its own unique set of rendering instructions. This approach enhances rendering efficiency and organization, particularly in complex scenes.

You can enable render group mode on any container using container.enableRenderGroup() or by initializing a new container with the render group property set to true (new Container({isRenderGroup: true})). The method you choose depends on your specific use case and setup requirements.

An important aspect of PixiJS’s rendering process is the automatic treatment of rendered scenes as render groups. This conversion streamlines the rendering process, but understanding when and how this happens is crucial to fully leverage its benefits.

One of the key advantages of using render groups is the performance efficiency in moving them. Since transformations are applied at the GPU level, moving a render group, even one with complex and numerous children, doesn't require recalculating the rendering instructions or performing transformations on each child. This makes operations like panning a large game world incredibly efficient.

However, it's crucial to note that render groups do not batch together. This means that turning every container into a render group could actually slow things down, as each render group is processed separately. It's best to use render groups judiciously, at a broader level, rather than on a per-child basis. This approach ensures you get the performance benefits without overburdening the rendering process.

RenderGroups maintain their own set of rendering instructions, ensuring that changes or updates within a render group don't affect the rendering instructions of its parent or other render groups. This isolation ensures more stable and predictable rendering behavior.

Additionally, renderGroups can be nested, allowing for powerful options in organizing different aspects of your scene. This feature is particularly beneficial for separating complex game graphics from UI elements, enabling intricate and efficient scene management in complex applications.

This means that Containers have 3 levels of matrix to be mindful of:

  1. localTransform, this is the transform of the container based on its own properties
  2. groupTransform, this it the transform of the container relative to the renderGroup it belongs too
  3. worldTransform, this is the transform of the container relative to the Scene being rendered

Usage

Basic

<script>
  import { Container, Text } from 'svelte-pixi'
</script>


<Container x={360} y={160}>
  <Text text="Hello" x={0} y={0} anchor={0.5} style={{ fill: 'white' }} />
  <Text text="World" x={0} y={60} anchor={0.5} style={{ fill: 'white' }} />
</Container>

The Instance Prop

The instance prop allows you to change or aceess the underlying PIXI instance. This is how components such as Sprite are composed, and all components that extend PIXI.Container can be used in this way.

MyCustomTextComponent.svelte
<script>
  import { Container } from 'svelte-pixi'
  import * as PIXI from 'pixi.js'


  let {
    text = 'hello world',
    style = { fill: 'white' }
  } = $props()


  const instance = new PIXI.Text({ text, style })


  // updating the instance
  $effect(() => {
    instance.text = text
  })
</script>


<Container {instance} x={280} y={170} />

You can also bind to it to access the default one:

<script>
  import { Container } from 'svelte-pixi'
  import * as PIXI from 'pixi.js'


  let instance


  $effect(() => console.log(instance.label))
</script>


<Container bind:instance label="my container"/>

API

Props

* denotes required

NameDescription
accessible
boolean

Flag for if the object is accessible. If true AccessibilityManager will overlay a shadow div with attributes set

accessibleChildren
boolean

Setting to false will prevent any children inside this container to be accessible. Defaults to true.

accessibleHint
nullstring

Sets the aria-label attribute of the shadow div

accessiblePointerEvents
"visible""auto""none""visiblePainted""visibleFill""visibleStroke""painted""fill""stroke""all""inherit"

Specify the pointer-events the accessible div will use Defaults to auto.

accessibleTitle
nullstring

Sets the title attribute of the shadow div If accessibleTitle AND accessibleHint has not been this will default to 'container [tabIndex]'

accessibleType
string

Specify the type of div the accessible layer is. Screen readers treat the element differently depending on this type. Defaults to button.

alpha
number
angle
number

The angle of the object in degrees. 'rotation' and 'angle' have the same effect on a display object; rotation is in radians, angle is in degrees.

boundsArea
PIXI.Rectangle

An optional bounds area for this container. Setting this rectangle will stop the renderer from recursively measuring the bounds of each children and instead use this single boundArea. This is great for optimisation! If for example you have a 1000 spinning particles and you know they all sit within a specific bounds, then setting it will mean the renderer will not need to measure the 1000 children to find the bounds. Instead it will just use the bounds you set.

cacheAsBitmap
boolean

Legacy property for backwards compatibility with PixiJS v7 and below. Use cacheAsTexture instead.

cacheAsTexture
PIXI.CacheAsTextureOptionsboolean
cullable
boolean

Should this object be rendered if the bounds of this object are out of frame?

Culling has no effect on whether updateTransform is called.

cullableChildren
boolean

Determines if the children to the container can be culled Setting this to false allows PixiJS to bypass a recursive culling function Which can help to optimize very complex scenes

cullArea
PIXI.Rectangle

If set, this shape is used for culling instead of the bounds of this object. It can improve the culling performance of objects with many children. The culling area is defined in local space.

cursor
string

The cursor preferred when the mouse pointer is hovering over.

effects
PIXI.Effect[]
eventMode
"auto""none""passive""static""dynamic"

The mode of interaction for this object

filterArea
PIXI.Rectangle
filters
PIXI.FilterPIXI.Filter[]
height
number

The height of the Container, setting this will actually modify the scale to achieve the value set.

hitArea
nullPIXI.IHitArea

The hit-area specifies the area for which pointer events should be captured by this event target.

instance
T
interactive
boolean

Whether this event target should fire UI events.

interactiveChildren
boolean

Whether this event target has any children that need UI events. This can be used optimize event propagation.

isRenderGroup
boolean
label
string
mask
numberPIXI.Container<PIXI.ContainerChild>Partial<PIXI.MaskOptionsAndMask>
name
string
onadded
() => void

Called when the instance is added to its parent or stage

onclick
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'click' event

oncreate
(instance: T) => void

Called on creation of the component. You can use this to do any setup on the instance directly

onglobalmousemove
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'globalmousemove' event

onglobalpointermove
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'globalpointermove' event

onglobaltouchmove
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'globaltouchmove' event

onmousedown
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mousedown' event

onmouseenter
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mouseenter' event

onmouseleave
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mouseleave' event

onmousemove
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mousemove' event

onmouseout
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mouseout' event

onmouseover
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mouseover' event

onmouseup
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mouseup' event

onmouseupoutside
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'mouseupoutside' event

onpointercancel
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointercancel' event

onpointerdown
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointerdown' event

onpointerenter
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointerenter' event

onpointerleave
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointerleave' event

onpointermove
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointermove' event

onpointerout
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointerout' event

onpointerover
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointerover' event

onpointertap
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointertap' event

onpointerup
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointerup' event

onpointerupoutside
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'pointerupoutside' event

onremoved
() => void

Called when the instance removed from its parent or stage

onrightclick
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'rightclick' event

onrightdown
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'rightdown' event

onrightup
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'rightup' event

onrightupoutside
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'rightupoutside' event

ontap
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'tap' event

ontouchcancel
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'touchcancel' event

ontouchend
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'touchend' event

ontouchendoutside
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'touchendoutside' event

ontouchmove
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'touchmove' event

ontouchstart
nullPIXI.FederatedEventHandler<PIXI.FederatedPointerEvent>

Handler for 'touchstart' event

pivot
number[number, number]{ x: number; y: number }PIXI.Point

The center of rotation, scaling, and skewing for this display object in its local space. The position is the projection of pivot in the parent's local space.

By default, the pivot is the origin (0, 0).

position
number[number, number]{ x: number; y: number }PIXI.Point

The coordinate of the object relative to the local coordinates of the parent.

renderable
boolean

Can this object be rendered, if false the object will not be drawn but the transform will still be updated.

rotation
number

The rotation of the object in radians. 'rotation' and 'angle' have the same effect on a display object; rotation is in radians, angle is in degrees.

scale
number[number, number]{ x: number; y: number }PIXI.Point

The scale factors of this object along the local coordinate axes.

The default scale is (1, 1).

skew
number[number, number]{ x: number; y: number }PIXI.Point

The skew factor for the object in radians.

sortableChildren
boolean
tabIndex
number
visible
boolean

The visibility of the object. If false the object will not be drawn, and the transform will not be updated.

width
number

The width of the Container, setting this will actually modify the scale to achieve the value set.

x
number

The position of the container on the x axis relative to the local coordinates of the parent. An alias to position.x

y
number

The position of the container on the y axis relative to the local coordinates of the parent. An alias to position.y

zIndex
number

Snippets

NameType
childrenSnippet<[instance: T]>