Skip to Content
Kinemium

TextBox

An editable text field with a caret, selection, find bar, and optional code-editor features.

TextBox is the editable text input. It stores text, tracks a caret and selection, and can run as a plain field or as a code editor with line numbers, bracket matching, diagnostics, and a minimap.

Getting started

local box = Instance.new("TextBox")
box.Size = UDim2.new(0, 320, 0, 40)
box.PlaceholderText = "Enter a name"
box.TextSize = 18
box.ClearTextOnFocus = false
box.Parent = screenGui

box.Focused:Connect(function()
    print("editing")
end)

box.TextChanged:Connect(function()
    print("now", box.Text)
end)

Text and content

PropertyTypeAccessDefaultDescription
TextstringRead/write""Current contents. Writing it fires TextChanged.
PlaceholderTextstringRead/write""Hint shown while the field is empty.
TextEditablebooleanRead/writetrueWhether the user can modify the text.
ClearTextOnFocusbooleanRead/writefalseClear the field when it gains focus.
SelectAllOnFocusbooleanRead/writefalseSelect the whole contents on focus.
MultiLinebooleanRead/writefalseAccept line breaks. Changing it resets scroll and caret state.
WordWrapbooleanRead/writefalseWrap long lines. TextWrapped is an alias.
MaxLengthnumberRead/write-1Maximum characters, -1 for no limit. Values below -1 are raised to -1. Setting it below the current length truncates the text.

MaxLength counts characters, not bytes. It applies to user input and to programmatic writes.

Font and appearance

PropertyTypeAccessDefaultDescription
FontEnum.FontRead/writeEnum.Font.LegacyLegacy font selector. The setter also accepts a Font object or a family string.
FontFaceFontRead/writeBuilt-in Montserrat RegularFont object with family, weight, and style.
TextSizenumberRead/write16Font size in pixels, minimum 1.
TextColor3Color3Read/writeBlackText color.
PlaceholderColor3Color3Read/write(0.5, 0.5, 0.5)Placeholder color.
TextTransparencynumberRead/write0Text transparency, clamped to 0 through 1.
TextXAlignmentEnum.TextXAlignmentRead/writeLeftHorizontal alignment.
TextYAlignmentEnum.TextYAlignmentRead/writeCenterVertical alignment.

Assigning Font with an enum uses that font. Assigning a Font object stores the object through FontFace. Assigning a string treats it as a font family name.

Caret and selection

PropertyTypeAccessDefaultDescription
CursorPositionnumberRead/write1Caret position as a one-based character index.
SelectionStartnumberRead/write1Selection anchor as a one-based character index.
SelectionEndnumberRead/write1Selection end as a one-based character index.
SelectedTextstringRead-only""Currently selected text, or an empty string.
CaretScreenPositionVector2Read-only(0, 0)Last resolved caret position on screen.
CaretColor3Color3Read/write(0.25, 0.5, 1.0)Caret color.
SelectionColor3Color3Read/write(0.25, 0.5, 1.0)Selection highlight color.
SelectionTransparencynumberRead/write0.65Selection highlight transparency, clamped to 0 through 1.
FocusColor3Color3Read/write(0.25, 0.5, 1.0)Focus outline color.
KeyHandledbooleanRead/writefalseMarks the current key event as handled.

Positions are one-based character offsets, not byte offsets. Setting SelectionStart moves the anchor, and setting SelectionEnd moves the caret.

Buffers and counts

PropertyTypeAccessDefaultDescription
TextBufferCapacitynumberRead/write0Reserved buffer capacity in bytes, clamped to 0 through 256 MB.
TextByteLengthnumberRead-only0Length of Text in UTF-8 bytes.
MaxUndoEntriesnumberRead/write1000Undo history limit, clamped to 0 through 100000.
SyntaxHighlightMaxBytesnumberRead/write2 MBText size above which syntax highlighting is skipped, clamped to 0 through 128 MB.
LineCountnumberRead-onlyDerivedNumber of lines in the current text.
DiagnosticCountnumberRead-only0Number of diagnostics currently stored.

TextBufferCapacity reserves memory. It isn't a limit on the text length; MaxLength is.

Editor behavior

These settings control code-editor presentation. All are read/write unless noted.

PropertyTypeDefaultDescription
CodeEditorbooleanfalseEnables editor behavior. Changing it resets scroll and caret state.
ShowLineNumbersbooleantrueDraw the line-number gutter.
RelativeLineNumbersbooleanfalseShow line numbers relative to the caret.
HighlightCurrentLinebooleantrueHighlight the caret's line.
BracketMatchingbooleantrueHighlight matching brackets.
TabSpacesbooleantrueInsert spaces for tabs.
TabSizenumber4Spaces per tab, clamped to 1 through 16.
AutoIndentbooleantrueIndent new lines to match the previous line.
AutoClosebooleantrueInsert closing brackets and quotes automatically.
AutoIndentBracketsbooleantrueIndent after an opening bracket.
SmartHomebooleantrueMove Home to the first non-whitespace character first.
SmartBackspacebooleantrueBackspace by indentation level on whitespace.
ShowIndentGuidesbooleantrueDraw indentation guides.
HighlightActiveIndentGuidebooleantrueHighlight the guide for the caret's indentation.
ShowWhitespacebooleanfalseDraw whitespace characters.
ShowScrollbarbooleantrueShow the scrollbar.
ShowGutterSeparatorbooleantrueDraw a separator between gutter and text.
SmoothScrollingbooleantrueEase scrolling instead of jumping.
ShowMinimapbooleanfalseDraw the minimap.
MinimapWidthnumber76Minimap width, clamped to 24 through 200.
ScrollbarWidthnumber8Scrollbar width, clamped to 2 through 24.
EditorPaddingnumber8Padding inside the editor, clamped to 0 through 48.
EditorLineHeightnumber0Line height override, clamped to 0 through 128.
MouseWheelScrollLinesnumber3Lines per wheel step, clamped to 0.1 through 30.
ScrollXnumber0Horizontal scroll target, minimum 0.
ScrollYnumber0Vertical scroll target, clamped between 0 and the maximum scroll.

Find bar

PropertyTypeAccessDefaultDescription
FindVisiblebooleanRead/writefalseWhether the find bar is open. Setting it to false closes the bar and clears the active input state.
FindQuerystringRead/write""Find text. Writing it moves the find caret to the end of the query.
FindCaseSensitivebooleanRead/writefalseWhether matching is case sensitive.
ShowFindHighlightsbooleanRead/writetrueHighlight matches in the text.

Colors

PropertyTypeAccessDefaultDescription
FindMatchColor3Color3Read/write(0.92, 0.68, 0.25)Find match highlight.
LineNumberColor3Color3Read/write(0.54, 0.57, 0.63)Line-number text color.
CurrentLineColor3Color3Read/write(0.30, 0.48, 0.73)Current line highlight.
IndentGuideColor3Color3Read/write(0.47, 0.52, 0.61)Indentation guide color.
BracketMatchColor3Color3Read/write(0.45, 0.63, 0.95)Matching bracket highlight.
GutterColor3Color3Read/write(0.93, 0.94, 0.96)Gutter background.
MinimapColor3Color3Read/write(0.93, 0.94, 0.96)Minimap content color.
ScrollbarColor3Color3Read/write(0.54, 0.57, 0.64)Scrollbar color.

Methods

SignatureReturnsDescription
FindNext(): booleanWhether a match was foundMove to the next find match.
FindPrevious(): booleanWhether a match was foundMove to the previous find match.
OpenFind(): ()Open the find bar.
CloseFind(): ()Close the find bar.
GoToLine(line: number, column?: number, selectionLength?: number, focus?: boolean): ()Move the caret. line and column are one-based; column defaults to 1, selectionLength to 0, and focus to false.
CaptureFocus(): ()Give the box keyboard focus.
ReleaseFocus(): ()Remove keyboard focus.
IsFocused(): booleanCurrent focus stateWhether the box has keyboard focus.
SelectAll(): ()Select the entire text.
ClearSelection(): ()Collapse the selection to the caret.
CopySelection(): ()Copy the selected text to the clipboard.
Undo(): ()Undo the last edit.
Redo(): ()Redo the last undone edit.
InsertText(text: string): ()Insert text at the caret.
ReplaceRange(start: number, finish: number, text: string): ()Replace a character range. Bounds are one-based.
ClearDiagnostics(): ()Remove every stored diagnostic.
SetDiagnostics(list: {{table}}): ()Replace diagnostics with a list of tables containing Line, Column, EndColumn, and Message.
DiagnosticAtCursor(): table?Diagnostic or nilDiagnostic covering the caret.
DiagnosticAtPoint(x: number, y: number): table?Diagnostic or nilDiagnostic at a point in the text box's coordinate space.
PositionAtPoint(x: number, y: number): numberOne-based character indexCharacter position at a point relative to the text box.
GetWordRangeAtCursor(): table{start, finish, text}Word around the caret. Bounds are one-based.
GetLineAtCursor(): table{line, start, finish, text}Line containing the caret.

Diagnostic tables use the same shape as the entries passed to SetDiagnostics: Line, Column, EndColumn, and Message.

Events

EventArgumentsWhen it fires
FocusednoneThe box gains keyboard focus.
FocusLostenterPressed: booleanThe box loses focus. The flag is true when Enter caused the release.
TextChangednoneThe text changes, including programmatic writes. Read Text inside the callback.
KeyDowninput: InputObjectA key is pressed while the box has focus.

TextChanged doesn't pass the new text. Read the Text property instead. KeyDown passes an InputObject with UserInputType set to keyboard and the pressed KeyCode.

Notes

  • All caret and selection offsets are one-based characters. TextByteLength reports bytes, so the two numbers can differ for non-ASCII text.
  • Setting MaxLength below the current length truncates immediately.
  • MultiLine and CodeEditor reset scroll and caret state when changed.
  • TextBufferCapacity is a reservation. It doesn't cap input length.
  • FindVisible = false closes the bar and clears the find input state, but it doesn't clear FindQuery.
  • TextBox inherits every GuiObject member, including Size, Position, AnchorPoint, Visible, and the input events.
  • TextEditable = false stops user edits while leaving the text readable and selectable programmatically.

See also

  • TextLabel for read-only text.
  • TextButton for a clickable caption.
  • SyntaxHighlighter for code coloring rules.
  • GuiObject for layout and appearance.

On this page