Use Viewport component

Common example:

<Viewport worldWidth="2000" worldHeight="2000" clamp={ {direction: 'all'} } />

Properties

You can use all properties from Display Object

Viewport Options

The Viewport component supports several options inherited from pixi-viewport:

Option	Type	Description
drag	boolean or object	Enable dragging the viewport
wheel	boolean or object	Enable mouse wheel scrolling
pinch	boolean or object	Enable pinch to zoom
decelerate	boolean or object	Enable deceleration (momentum) after dragging
clamp	object	Restrict viewport movement

Example with options:

<Viewport 
  worldWidth="2000" 
  worldHeight="2000" 
  drag={true}
  wheel={true}
  pinch={true}
  decelerate={true}
  clamp={ {direction: 'all'} } 
/>

Viewport Events

The Viewport component supports all events from pixi-viewport:

Event	Description
bounce-x-end	Fired when bounce on the x-axis ends
bounce-x-start	Fired when bounce on the x-axis starts
bounce-y-end	Fired when bounce on the y-axis ends
bounce-y-start	Fired when bounce on the y-axis starts
clicked	Fired when viewport is clicked
drag-end	Fired when drag ends
drag-start	Fired when drag starts
frame-end	Fired when frame ends
mouse-edge-end	Fired when mouse-edge ends
mouse-edge-start	Fired when mouse-edge starts
moved	Fired when viewport moves
moved-end	Fired when viewport stops moving
pinch-end	Fired when pinch ends
pinch-start	Fired when pinch starts
snap-end	Fired when snap ends
snap-start	Fired when snap starts
snap-zoom-end	Fired when snap-zoom ends
snap-zoom-start	Fired when snap-zoom starts
wheel-scroll	Fired when mouse wheel is scrolled
zoomed	Fired when viewport is zoomed
zoomed-end	Fired when viewport stops zooming

Example with event:

<Viewport 
  worldWidth="2000" 
  worldHeight="2000"
/>

Viewport Follow Directive

The viewportFollow directive allows an element to be followed by the viewport. When applied, the viewport will automatically center on the element as it moves.

This directive must be used within a Viewport component context.

Usage

<Viewport worldWidth="2000" worldHeight="2000" clamp={ {direction: 'all'} }>
    <Rect viewportFollow x={0} y={0} width={100} height={100} color="red" />
</Viewport>

<script>
    const viewportFollow = true // null to disable
</script>

In this example, the red rectangle will be followed by the viewport, keeping it centered in the view as it moves around within the 2000x2000 world space.

Usage with options

<Viewport worldWidth="2000" worldHeight="2000" clamp={ {direction: 'all'} }>
    <Rect viewportFollow x={0} y={0} width={100} height={100} color="red" />
</Viewport>

<script>
    const viewportFollow = {
        speed: 0.1,
        acceleration: 0.1,
        radius: 100
    }
</script>

• speed number 0 optional to follow in pixels/frame (0=teleport to location)
• acceleration number optional set acceleration to accelerate and decelerate at this rate; speed cannot be 0 to use acceleration
• radius number optional radius (in world coordinates) of center circle where movement is allowed without moving the viewport * @returns {Viewport} this

Requirements

• Must be used on an element that is a child of a Viewport component
• The parent Viewport component must have defined dimensions (worldWidth and worldHeight)

WARNING

Important: When an element has viewportFollow set to true, it will automatically disable the dragging functionality of the parent viewport. This is by design as viewport dragging would conflict with the following behavior.

Performance Optimization

When rendering large numbers of elements (1000+) inside a Viewport, consider these optimization strategies:

1. Viewport Culling

The viewportCull directive automatically hides elements outside the visible area, significantly reducing render overhead:

<Viewport worldWidth="5000" worldHeight="5000" drag={true}>
  <Container viewportCull={true}>
    @for (item of items) {
      <Sprite image={@item.image} x={@item.x} y={@item.y} />
    }
  </Container>
</Viewport>

TIP

Culling is most effective when only a small portion of the world is visible at once. If most elements are always on screen, culling overhead may not be worth it.

2. Reduce Signal Granularity

Instead of creating signals for every animated property, use direct Pixi manipulation in tick():

<script>
  import { tick, mount } from 'canvasengine';
  
  // BAD: 5 signals per element = expensive with 1000+ elements
  const items = signal(data.map(d => ({
    x: signal(d.x),
    y: signal(d.y),
    rotation: signal(0),    // Don't do this for animations!
    alpha: signal(1),       // Don't do this for animations!
    scale: signal(1),       // Don't do this for animations!
  })));
  
  // GOOD: Only position signals, animate imperatively
  const items = signal(data.map(d => ({
    x: signal(d.x),
    y: signal(d.y),
    rotationSpeed: Math.random() * 0.1,
  })));
  
  tick((tickValue, element) => {
    const viewport = element.componentInstance.children[0];
    viewport.children.forEach((sprite, i) => {
      sprite.rotation += items()[i].rotationSpeed;
    });
  });
</script>

3. Throttle Updates

For non-critical animations, update every N frames instead of every frame:

<script>
  tick((tickValue) => {
    if (tickValue.frame % 2 !== 0) return; // Skip every other frame
    
    // Animation logic here
  });
</script>

4. Level of Detail (LOD)

Reduce animation complexity based on element count:

<script>
  tick((tickValue, element) => {
    const count = items().length;
    
    sprites.forEach(sprite => {
      sprite.rotation += 0.01; // Always animate rotation
      
      if (count < 3000) {
        sprite.alpha = Math.sin(tickValue.frame * 0.05); // Alpha only below 3k
      }
      if (count < 1000) {
        sprite.scale.set(1 + Math.sin(tickValue.frame * 0.02) * 0.1); // Scale only below 1k
      }
    });
  });
</script>

Performance Summary

Element Count	Recommended Strategy
< 500	Full reactivity (signals for all props)
500 - 2000	Imperative animations + position signals
2000 - 5000	+ Viewport culling + throttled updates
> 5000	+ LOD + consider chunked rendering

Common Properties

Property	Type	Description
x	number	X-coordinate position of the display object.
y	number	Y-coordinate position of the display object.
width	number	Width of the display object.
height	number	Height of the display object.
scale	object	Scale of the display object.
anchor	object	Anchor point of the display object.
skew	object	Skew of the display object.
tint	number	Tint color of the display object.
rotation	number	Rotation of the display object in radians.
angle	number	Rotation of the display object in degrees.
zIndex	number	Z-index of the display object.
roundPixels	boolean	Whether to round pixel values.
cursor	string	Cursor style when hovering over the display object.
visible	boolean	Visibility of the display object.
alpha	number	Alpha transparency of the display object.
pivot	object	Pivot point of the display object.
filters	array	Filters applied to the display object.
maskOf	Element	Element that this display object masks.
blendMode	string	Blend mode for rendering.
filterArea	object	Filter area for rendering.

Layout Properties

Pour obtenir la documentation complète et détaillée sur toutes les propriétés de mise en page, consultez la documentation officielle de PixiJS Layout.

Sizing and Dimensions

Property	Type	Description
width	number/string	Width of the display object. Accepts pixels or percentage (e.g. '50%').
height	number/string	Height of the display object. Accepts pixels or percentage (e.g. '50%').
minWidth	number/string	Minimum width the object can shrink to.
minHeight	number/string	Minimum height the object can shrink to.
maxWidth	number/string	Maximum width the object can expand to.
maxHeight	number/string	Maximum height the object can expand to.
aspectRatio	number	Ratio between width and height (e.g. 1.5 for 3:2 ratio).

Flex Layout

Property	Type	Description
flexDirection	string	Direction of flex items. Values: 'row', 'column', 'row-reverse', 'column-reverse'.
flexWrap	string	Whether items wrap. Values: 'wrap', 'nowrap', 'wrap-reverse'.
justifyContent	string	Alignment along main axis. Values: 'flex-start', 'flex-end', 'center', 'space-between', 'space-around'.
alignItems	string	Alignment along cross axis. Values: 'flex-start', 'flex-end', 'center', 'stretch', 'baseline'.
alignContent	string	Alignment of lines with multiple items. Values: 'flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around'.
alignSelf	string	Override of parent's alignItems for specific item.
flexGrow	number	Grow factor of item relative to other items.
flexShrink	number	Shrink factor of item relative to other items.
flexBasis	number/string	Initial size of item before flex growing/shrinking.
gap	number/object	Gap between items.
rowGap	number	Gap between rows.
columnGap	number	Gap between columns.

Positioning

Property	Type	Description
positionType	string	Type of positioning. Values: 'relative', 'absolute', 'static'.
top	number/string	Distance from the top edge.
right	number/string	Distance from the right edge.
bottom	number/string	Distance from the bottom edge.
left	number/string	Distance from the left edge.

Spacing, Margins and Borders

Property	Type	Description
margin	number/array	Space outside border box. Can be single value or array for different sides.
padding	number/array	Space inside border box. Can be single value or array for different sides.
border	number/array	Border width. Can be single value or array for different sides.

Object Fitting and Alignment

Property	Type	Description
objectFit	string	How object is resized to fit layout box. Values: 'contain', 'cover', 'fill', 'none', 'scale-down'.
objectPosition	string	Anchor point of object inside layout box. E.g. 'center', 'top left'.
transformOrigin	string	Pivot point for rotation and scaling of layout box.

Shadow

Property	Type	Description
blur	number	Blur strength.
color	number	Color of the shadow.
offset	object	Offset of the shadow.
quality	number	Quality of the shadow.

Hook before destroy

<script>
  import {
    signal,
    animatedSignal,
    effect,
    animatedSequence,
  } from "canvasengine";
  import MyViewport from "./viewport.ce";
  
  let bool = signal(true)
  const opacity = animatedSignal(1, { duration: 500 });

  const click = async () => {
    bool.set(!bool())
  }

  const beforeDestroy = async () => {
    await animatedSequence([
      () => opacity.set(0),
    ])
    console.log("before destroy")
  }
</script>


<Canvas antialias={true}>
     <Container onBeforeDestroy={beforeDestroy}>
        @if (bool) {
            <Rect width={300} height={300} color="red" alpha={opacity} click />
        }
    </Container>
</Canvas>