<Screen/>

The <Screen/> component turns an <Entity/> into a 2D UI screen that lays out <Element/> children. By default it renders in screen space (a 2D overlay), but it can also be placed in world space for in-scene UI. Use referenceResolution and scaleMode to control how the UI scales across different display sizes.

Usage

Attach a <Screen/> to an <Entity/>, then nest entities carrying an <Element/> to draw text or images.

<Entity name="screen">
  <Screen referenceResolution={[1280, 720]} />
  <Entity name="label">
    <Element type="text" text="Hello, World!" />
  </Entity>
</Entity>

This example renders a centred line of screen-space text using a <Screen/> and a text <Element/>.

Demo

Screen-space text - View Code

Code

TextExample.jsx

import { Application, Entity } from '@playcanvas/react';
import { Camera, Screen, Element } from '@playcanvas/react/components';
import { useFont } from '@playcanvas/react/hooks';

const TextScene = () => {
  // An MSDF font asset generated with font-tools (https://playcanvas.github.io/font-tools/).
  // Loading the .json automatically pulls in the sibling .png atlas page(s).
  const { asset: font } = useFont('/assets/fonts/source-sans.json');

  if (!font) return null;

  return (
    <Entity>
      {/* A camera to render the UI */}
      <Entity name="camera">
        <Camera clearColor="#1a1a2e" />
      </Entity>

      {/* A screen-space UI screen with a centred line of text */}
      <Entity name="screen">
        <Screen referenceResolution={[1280, 720]} />
        <Entity name="label">
          <Element
            type="text"
            fontAsset={font}
            text="Hello, World!"
            fontSize={84}
            anchor={[0.5, 0.5, 0.5, 0.5]}
            pivot={[0.5, 0.5]}
          />
        </Entity>
      </Entity>
    </Entity>
  );
};

const TextExample = () => (
  <Application>
    <TextScene />
  </Application>
);

export default TextExample;

Learn more about the Screen Component in the PlayCanvas documentation.

Properties

Name	Type	Default
screenSpace?	boolean Whether the screen is rendered in screen space.	true
referenceResolution?	[number, number] The reference resolution of the screen.	[1280, 720]
scaleMode?	"blend" | "stretch" | "fit" The scale mode of the screen.	"blend"
cull?	boolean If true, then elements inside this screen will not be rendered when outside of the screen (only valid when screenSpace is true).	-
resolution?	[number, number] Sets the width and height of the ScreenComponent. When screenSpace is true, the resolution will always be equal to GraphicsDevice#width by GraphicsDevice#height . Gets the width and height of the ScreenComponent.	-
scaleBlend?	number Sets the scale blend. This is a value between 0 and 1 that is used when scaleMode is equal to SCALEMODE_BLEND. Scales the ScreenComponent with width as a reference (when value is 0), the height as a reference (when value is 1) or anything in between. Defaults to 0.5. Gets the scale blend.	-
priority?	number Sets the screen's render priority. Priority determines the order in which ScreenComponents in the same layer are rendered. Number must be an integer between 0 and 127. Priority is set into the top 8 bits of the ElementComponent#drawOrder property. Defaults to 0. Gets the screen's render priority.	-
system?	ComponentSystem The ComponentSystem used to create this Component.	-
entity?	Entity The Entity that this Component is attached to.	-
enabled?	boolean Sets the enabled state of the component. Gets the enabled state of the component.	-