> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/development/api-reference/classes/textbox.md).

# TextBox

TextBox : `GuiObject`

## Overview

A UI element that lets players type text with the keyboard. It is used to receive strings from players, such as nicknames or coupon codes.

The entered text is stored in the Text property, and the FocusLost event indicates when input is finished. The guide text shown before input is specified with the PlaceholderText property.

**Important Notes**

* TextBox can be controlled only in **client environment**. Accessing the TextBox-specific properties, methods, or events from a server Script causes an error. To use the entered value on the server, send it with a RemoteEvent.
* A TextBox under a SurfaceGui or BillboardGui does not receive input.

## Properties

### ClearTextOnFocus

`boolean`

Specifies whether the existing Text is cleared when the TextBox gains focus.

The default is false. If true, Text becomes an empty string when the TextBox gains focus by a click or CaptureFocus(). If TextEditable is false, the text is not cleared.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.ClearTextOnFocus = true
```

### CursorPosition

`number`

Specifies the position of the text cursor in bytes.

1 means the position before the first byte of Text, and the value is -1 when the TextBox is not being edited. If Text contains characters made of multiple bytes, the value can differ from the number of characters, and a value in the middle of a character is adjusted to the nearest character boundary.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocused()
    TextBox.CursorPosition = #TextBox.Text + 1
end
TextBox.Focused:Connect(OnFocused)
```

### FontFace

`Font`

Specifies the font applied to the text and PlaceholderText displayed in the TextBox.

The font family, weight, and style are specified together.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.FontFace = Font.fromName("Fredoka", Enum.FontWeight.Bold, Enum.FontStyle.Normal)
```

### LineHeight

`number`

Specifies the line spacing scale of multi-line text.

The default is 1, and values from 0 to 3 can be used. A value outside the range is adjusted to the nearest value, and if the value is 0, lines are displayed overlapping each other.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.LineHeight = 1.5
```

### LocalizedPlaceholderText

`string`

A read-only property that represents PlaceholderText automatically translated based on the current client's locale.

In a TextBox, the AutoLocalize property applies to PlaceholderText instead of Text, and translation is applied only when AutoLocalize is true.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

print(TextBox.LocalizedPlaceholderText)
```

### MultiLine

`boolean`

Specifies whether multiple lines can be entered in the TextBox.

The default is false. If false, pressing the Enter key finishes input and releases focus. If true, the Enter key inserts a line break, and the FocusLost and ReturnPressedFromOnScreenKeyboard events do not fire.

When set to true, it is recommended to provide a separate button to confirm the input. Line breaks already entered are kept even if the value is changed to false.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.MultiLine = true
```

### PlaceholderColor3

`Color3`

Specifies the color of PlaceholderText.

The default is (127, 127, 127).

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.PlaceholderColor3 = Color3.fromRGB(180, 180, 180)
```

### PlaceholderText

`string`

Specifies the guide text displayed instead when Text is an empty string.

The default is "TextBox". The color is specified with PlaceholderColor3, and the same FontFace, TextSize, and TextTransparency values as Text are applied.

Up to 20,000 bytes can be stored. Assigning a longer string causes an error, and the existing value is kept.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.PlaceholderText = "Enter your nickname"
```

### SelectionStart

`number`

Specifies the start position of the selected text range in bytes.

The value is -1 when no range is selected, and it becomes -1 together with CursorPosition when editing ends. Use it together with CursorPosition to read or specify the selected range.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocused()
    TextBox.SelectionStart = 1
    TextBox.CursorPosition = #TextBox.Text + 1
end
TextBox.Focused:Connect(OnFocused)
```

### Text

`string`

Specifies the text displayed in the TextBox.

The text entered by the player is also stored in this property. The default is an empty string, and PlaceholderText is displayed while it is empty.

Up to 20,000 bytes can be stored. Assigning a longer string causes an error, and the existing value is kept.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.Text = "Player"
```

### TextColor3

`Color3`

Specifies the color applied to the entered text.

The default is (0, 0, 0), and the color of PlaceholderText is specified separately with PlaceholderColor3.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextColor3 = Color3.fromRGB(255, 255, 255)
```

### TextEditable

`boolean`

Specifies whether the player can change Text through input.

The default is true. If false, the TextBox cannot gain focus, so the cursor is not displayed and calling CaptureFocus() does nothing. Selecting the existing text and changing Text with a script are still possible.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextEditable = false
```

### TextScaled

`boolean`

Specifies whether text size is automatically adjusted to fill the entire area of the TextBox.

If true, the TextSize value is ignored and TextWrapped changes to true. TextWrapped stays true even if TextScaled is changed back to false, and changing TextWrapped to false while TextScaled is true also changes TextScaled to false.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextScaled = true
```

### TextSize

`number`

Specifies the size of the text in pixels.

The default is 14, and values from 1 to 100 can be used. A value outside the range is adjusted to the nearest value.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextSize = 24
```

### TextTransparency

`number`

Specifies the transparency of the text and PlaceholderText.

0 means completely opaque, and 1 means completely invisible.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextTransparency = 0.5
```

### TextWrapped

`boolean`

Specifies whether text is divided into multiple lines when it exceeds the width of the TextBox.

Lines are divided based on space characters.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextWrapped = true
```

### TextXAlignment

`Enum.TextXAlignment`

Specifies whether text is placed in the left, center, or right section of the TextBox area.

The default is Center.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextXAlignment = Enum.TextXAlignment.Left
```

### TextYAlignment

`Enum.TextYAlignment`

Specifies whether text is placed in the top, center, or bottom section of the TextBox area.

The default is Center.

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox.TextYAlignment = Enum.TextYAlignment.Top
```

## Methods

### CaptureFocus

A method that sets focus on the TextBox to start input.

When the TextBox gains focus, the Focused event fires, and if another TextBox had focus, that TextBox loses focus first. If TextEditable or Visible is false, or if the TextBox is under a disabled ScreenGui, this method does nothing.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

TextBox:CaptureFocus()
```

### IsFocused

A method that returns whether the TextBox has focus.

#### Parameters

#### Return

| `boolean` | true if the TextBox has focus; otherwise false. |
| --------- | ----------------------------------------------- |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local IsFocused = TextBox:IsFocused()
print("IsFocused : ", IsFocused)
```

### ReleaseFocus

A method that releases focus from the TextBox.

When focus is released, the FocusLost event fires, and inputThatCausedFocusLoss is nil. If the TextBox does not have focus, this method does nothing.

#### Parameters

| `boolean` InSubmitted | (Optional) The value passed as enterPressed of the FocusLost event. If omitted, false is used. |
| --------------------- | ---------------------------------------------------------------------------------------------- |

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local Submitted = true
TextBox:ReleaseFocus(Submitted)
```

## Events

### Focused

An event that fires when the TextBox gains focus.

It fires when the player clicks or taps the TextBox, or when CaptureFocus() is called.

#### Parameters

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocused()
    print("Focused")
end
TextBox.Focused:Connect(OnFocused)
```

### FocusLost

An event that fires when the TextBox loses focus.

It fires when input is finished with the Enter key, when the player clicks outside the TextBox, or when ReleaseFocus() is called. It is mainly used to check the entered Text.

#### Parameters

| `boolean` enterPressed                 | true if focus was released by pressing the Enter key (the Return key on mobile). If focus was released by ReleaseFocus(), the submitted value is passed. |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InputObject` inputThatCausedFocusLoss | The input that released focus. It is nil if focus was released by ReleaseFocus() or by CaptureFocus() of another TextBox.                                |

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnFocusLost(enterPressed, inputThatCausedFocusLoss)
    if enterPressed then
        print("Submitted : ", TextBox.Text)
    end
end
TextBox.FocusLost:Connect(OnFocusLost)
```

### ReturnPressedFromOnScreenKeyboard

An event that fires when the Enter key is pressed while the TextBox has focus.

On mobile, it fires when the Return key or the done key of the on-screen keyboard is pressed, and it fires before the FocusLost event. If MultiLine is true, the Enter key inserts a line break, so this event does not fire.

#### Parameters

#### Code Samples

```lua
local ScreenGui = script.Parent
local TextBox = ScreenGui:WaitForChild("TextBox")

local function OnReturnPressed()
    print("ReturnPressedFromOnScreenKeyboard")
end
TextBox.ReturnPressedFromOnScreenKeyboard:Connect(OnReturnPressed)
```

## See also

{% content-ref url="/pages/Hgp8bh8C44modKPwUBkg" %}
[GUI](https://docs.overdare.com/manual/studio-manual/gui.md)
{% endcontent-ref %}

{% content-ref url="/pages/SZGuVp7JPyahII6ztV8f" %}
[InputObject](https://docs.overdare.com/development/api-reference/classes/inputobject.md)
{% endcontent-ref %}
