UI Text

Ad text to your UI by creating a Label entity.

A Label entity has the following fields that can be configured:

• value: The string to display
• fontSize: The size of the text, as a number.

  NOTE: The fontSize is not affected by the size of its entity or parent entities.

• color: The color of the text, as a Color4 .
• font: The font to use, taking a value from the Font enum. Supported values are:
  • serif
  • sans-serif (default)
  • monospace
• textAlign: How the text will align with its parent. It takes a value from the TextAlingType type. TextAlignType = ’top-left’ | ’top-center’ | ’top-right’ | ‘middle-left’ | ‘middle-center’ | ‘middle-right’ | ‘bottom-left’ | ‘bottom-center’ | ‘bottom-right’;

📔 Note: The fontSize is not affected by the size of its entity or parent entities.

A Label entity can also have other common components found on other types of UI entities, like uiTransform and uiBackground.

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'

ReactEcsRenderer.setUiRenderer(() => (
	<UiEntity uiTransform={{ width: 'auto', height: 'auto' }}>
		<Label
			value="This is a label"
			color={Color4.Red()}
			fontSize={29}
			font="serif"
			textAlign="top-left"
		/>
	</UiEntity>
))

For multi-line text, you can add line breaks into the string, using \n.

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'

ReactEcsRenderer.setUiRenderer(() => (
	<UiEntity uiTransform={{ width: 700, height: 400 }}>
		<Label value="Hello World,\nthis message is quite long and won't fit in a single line.\nI hope that's not a problem." />
	</UiEntity>
))

To make a container’s size always adjust to the text’s length, set the height and width of the uiTransform to auto.

import { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs'

ReactEcsRenderer.setUiRenderer(() => (
	<UiEntity
		uiTransform={{
			width: 'auto',
			height: 'auto',
			alignSelf: 'center',
			padding: 10,
		}}
		uiBackground={{
			color: Color4.Red(),
		}}
		uiText={{
			value: 'Hello world!',
			fontSize: 18,
		}}
	/>
))

Responsive text size #

Use the scaleFontSize() function to provide font values that adjust to the player’s screen size. When setting the fontSize property of a text UI entity, pass this function instead of a single number.

import { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs'
import { scaleFontSize } from '@dcl/sdk/react-ecs'

ReactEcsRenderer.setUiRenderer(() => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: 'Hello world!',
      fontSize={scaleFontSize(15)}
    }}
  />
))

The scaleFontSize() function requires two parameters:

• fontSize: The base font size to use.
• scaleUnit (optional): The scaling factor. This determines if the text should be adjusted based on the screen width or the height, and a multiplier for how much to adapt. Default: "0.39vh". Values can be:
  • Number: A simple number, in this case it gets interpreted as relative to width
  • String ending in vw: This makes the number relative to the view width. For example "0.8vw"
  • String ending in vh: This makes the number relative to the view height. For example "0.8vh"

💡 Tip: This function works similar to the CSS calc() function.

The value of scaleUnit is a percentage of the window’s width or height. So a scaleUnit of "100vw" is 100% of the width of the screen, a value of "0.5vw" is 0.5% of the width of the screen.

The formula that scaleFontSize() follows is it multiples the screen width or height by the scaleUnit and adds to that the fontSize passed in the first parameter.

final font = fontSize + (screen width * scaleUnit / 100 )

For example, in the snippet below uses a scaleUnit value of 0.8. If the screen width is 1280px that will result in text of size of 26.84, having followed the equation 15 + (1280 * 0.8 / 100).

import { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs'
import { scaleFontSize } from '@dcl/sdk/react-ecs'

ReactEcsRenderer.setUiRenderer(() => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: 'Hello world!',
      fontSize={scaleFontSize(15, 0.8)}
    }}
  />
))

💡 Tip: If you don’t have different screen sizes to test, you can try resizing the window where you run the preview. The text will adjust instantly every time you change the window.