search
githubEdit

UI Special Types

Special entitiy types for the UI, including dropdowns and input boxes.

There are certain special entity types that allow for some special kinds of interactions.

hashtag
Dropdown

Create a Dropdown entity to allow users to expand and select an item from a list.

A Dropdown entity must have at least the following properties:

  • options: What values to display when the dropdown is expanded. Provide an object containting an arraw with a string value for each option. The first value in the array is displayed as the default option.

  • onChange: A function that is executed every time that a value is selected in the dropdown, using

You can also configure other comopnents of the Dropdown entity, like a uiTransform, as in other UI entities.

ui.tsx file:

import { UiEntity, Label, Dropdown, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'
import { Color4Type } from '@dcl/sdk/ecs'

function selectOption(index: number) {
  switch (index) {
    case 0:
      textColor = Color4.Red()
      break
    case 1:
      textColor = Color4.Blue()
      break
    case 2:
      textColor = Color4.Green()
      break
  }
}

let textColor: Color4Type = Color4.Red()

export const uiMenu = () => (
    <UiEntity
      uiTransform={{
        width: '200px',
        height: '100px',
        alignContent: 'auto',
        flexDirection: 'column',
        alignSelf: 'center',
      }}
    >
      <Label
        value="Select a color"
        fontSize={18}
        color={textColor}
        uiTransform={{
          width: '140px',
          height: '40px',
        }}
      />
      <Dropdown
        options={[`Red`, `Blue`, `Green`]}
        onChange={selectOption}
        uiTransform={{
          width: '100px',
          height: '40px',
        }}
      />
    </UiEntity>
)

index.ts file:

circle-exclamation

📔 Note: All the following snippets in this page assume that you have a .ts similar to the above, running the ReactEcsRenderer.setUiRenderer() function.

hashtag
Input text

Create an Input entity to allow users to to type in text. Players must first click on this box before they can write into it.

The behavior of the Input entity is managed via the following properties:

  • onSubmit: A function that is executed when the player hits Return/Enter, using the provided text as input. The text field is cleared when this happens.

  • onChange: A function that is executed every time that a value in the input text is changed. As the player types into the box, this function is executed once for each character that is added or removed. It also gets called when the player hits Return/Enter and the text is cleared.

  • disable: If true, the player won't be able to interact with the input entity.

The following example uses onSubmit to log the provided text to the console.

It's a good practice to provide both a button for submitting and handling the "onSubmit" event when the player presses the Enter/Return key. The following example shows how you can do this. Note that for consistency, the function carried out by the button is manually clearing the text in the input field.

circle-info

💡 Tip: The example above sets the value property of the input text to a variable. With this, you can change the displayed text by simply changing the variable. This allows you to do things like clearing the text, changing placeholder values, or even implementing autocorrect functionalities.

The following properties are also available to customize the look of the text field, most of them similar to those present in Label entities:

  • placeHolder: String to display before the player starts inputing anything. It's useful to make this text a hint about what they should write.

  • placeHolderColor: The color to use for the placeholder text, as a Color4.

circle-info

💡 Tip: Use a paler shade of the color of text that the player writes.

  • 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 the player writes, as a Color4.

circle-exclamation

📔 Note: Make sure you use a different color from the placeHolderColor.

  • font: The font to use, taking a value from the Font enum. Supported values are: - F_SANS_SERIF - F_SERIF (default) - F_MONOSPACE

  • textAlign: How the text will align with its parent. It takes a value from the `TextAlignType`. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

You can also configure other components of the Input entity, like a uiTransform, OnMouseDown as in other UI entities.

PreviousUI Button EventsNextUI Text

Last updated