Skip to content

Use Viewport component

Common example:

html
<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:

OptionTypeDescription
dragboolean or objectEnable dragging the viewport
wheelboolean or objectEnable mouse wheel scrolling
pinchboolean or objectEnable pinch to zoom
decelerateboolean or objectEnable deceleration (momentum) after dragging
clampobjectRestrict viewport movement

Example with options:

html
<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:

EventDescription
bounce-x-endFired when bounce on the x-axis ends
bounce-x-startFired when bounce on the x-axis starts
bounce-y-endFired when bounce on the y-axis ends
bounce-y-startFired when bounce on the y-axis starts
clickedFired when viewport is clicked
drag-endFired when drag ends
drag-startFired when drag starts
frame-endFired when frame ends
mouse-edge-endFired when mouse-edge ends
mouse-edge-startFired when mouse-edge starts
movedFired when viewport moves
moved-endFired when viewport stops moving
pinch-endFired when pinch ends
pinch-startFired when pinch starts
snap-endFired when snap ends
snap-startFired when snap starts
snap-zoom-endFired when snap-zoom ends
snap-zoom-startFired when snap-zoom starts
wheel-scrollFired when mouse wheel is scrolled
zoomedFired when viewport is zoomed
zoomed-endFired when viewport stops zooming

Example with event:

html
<Viewport 
  worldWidth="2000" 
  worldHeight="2000"
  drag-start={(event) => console.log('Drag started', event)}
/>

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

html
<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
</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

html
<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.

Common Properties

PropertyTypeDescription
xnumberX-coordinate position of the display object.
ynumberY-coordinate position of the display object.
widthnumberWidth of the display object.
heightnumberHeight of the display object.
scaleobjectScale of the display object.
anchorobjectAnchor point of the display object.
skewobjectSkew of the display object.
tintnumberTint color of the display object.
rotationnumberRotation of the display object in radians.
anglenumberRotation of the display object in degrees.
zIndexnumberZ-index of the display object.
roundPixelsbooleanWhether to round pixel values.
cursorstringCursor style when hovering over the display object.
visiblebooleanVisibility of the display object.
alphanumberAlpha transparency of the display object.
pivotobjectPivot point of the display object.
flexDirectionstringFlex direction for layout. Possible values: 'row', 'column', 'row-reverse', 'column-reverse'.
flexWrapstringFlex wrap for layout. Possible values: 'wrap', 'nowrap', 'wrap-reverse'.
justifyContentstringJustify content for layout. Possible values: 'flex-start', 'flex-end', 'center', 'space-between', 'space-around'.
alignItemsstringAlign items for layout. Possible values: 'auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline', 'space-between', 'space-around'.
alignContentstringAlign content for layout. Possible values: 'flex-start', 'flex-end', 'center', 'stretch', 'baseline', 'space-between', 'space-around'.
alignSelfstringAlign self for layout. Possible values: 'auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline', 'space-between', 'space-around'.
marginobjectMargin for layout.
paddingobjectPadding for layout.
gapobjectGap for layout.
borderobjectBorder for layout.
positionTypestringPosition type for layout.
filtersarrayFilters applied to the display object.
maskOfElementElement that this display object masks.
blendModestringBlend mode for rendering.
filterAreaobjectFilter area for rendering.

shadow

PropertyTypeDescription
PropertyTypeDescription
blurnumberBlur strength.
colornumberColor of the shadow.
offsetobjectOffset of the shadow.
qualitynumberQuality of the shadow.