Class LineEdit

An input field for single-line text.

Inheritance: Control

CanvasItem

Node

Object

LineEdit

Remarks

LineEdit provides an input field for editing a single line of text.

When the LineEdit control is focused using the keyboard arrow keys, it will only gain focus and not enter edit mode.
To enter edit mode, click on the control with the mouse, see also keep_editing_on_text_submit.
To exit edit mode, press ui_text_submit or ui_cancel (by default Escape) actions.
Check edit, unedit, is_editing, and LineEdit.editing_toggled for more information.

Important:

Focusing the LineEdit with ui_focus_next (by default Tab) or ui_focus_prev (by default Shift + Tab) or grab_focus still enters edit mode (for compatibility).

LineEdit features many built-in shortcuts that are always available (Ctrl here maps to Cmd on macOS):

Ctrl + C: Copy
Ctrl + X: Cut
Ctrl + V or Ctrl + Y: Paste/"yank"
Ctrl + Z: Undo
Ctrl + ~: Swap input direction.
Ctrl + Shift + Z: Redo
Ctrl + U: Delete text from the caret position to the beginning of the line
Ctrl + K: Delete text from the caret position to the end of the line
Ctrl + A: Select all text
Up Arrow/Down Arrow: Move the caret to the beginning/end of the line

On macOS, some extra keyboard shortcuts are available:

Cmd + F: Same as Right Arrow, move the caret one character right
Cmd + B: Same as Left Arrow, move the caret one character left
Cmd + P: Same as Up Arrow, move the caret to the previous line
Cmd + N: Same as Down Arrow, move the caret to the next line
Cmd + D: Same as Delete, delete the character on the right side of caret
Cmd + H: Same as Backspace, delete the character on the left side of the caret
Cmd + A: Same as Home, move the caret to the beginning of the line
Cmd + E: Same as End, move the caret to the end of the line
Cmd + Left Arrow: Same as Home, move the caret to the beginning of the line
Cmd + Right Arrow: Same as End, move the caret to the end of the line

Note: Caret movement shortcuts listed above are not affected by shortcut_keys_enabled.

Properties

alignment

Text alignment as defined in the HorizontalAlignment enum.

var alignment : int = 0

Property Value

int

Remarks

void set_horizontal_alignment(int value)
int get_horizontal_alignment

caret_blink

If true, makes the caret blink.

var caret_blink : bool = false

Property Value

bool

Remarks

void set_caret_blink_enabled(bool value)
bool is_caret_blink_enabled

caret_blink_interval

The interval at which the caret blinks (in seconds).

var caret_blink_interval : float = 0.65

Property Value

float

Remarks

void set_caret_blink_interval(float value)
float get_caret_blink_interval

caret_column

The caret's column position inside the LineEdit. When set, the text may scroll to accommodate it.

var caret_column : int = 0

Property Value

int

Remarks

void set_caret_column(int value)
int get_caret_column

caret_force_displayed

If true, the LineEdit will always show the caret, even if not editing or focus is lost.

var caret_force_displayed : bool = false

Property Value

bool

Remarks

void set_caret_force_displayed(bool value)
bool is_caret_force_displayed

caret_mid_grapheme

Allow moving caret, selecting and removing the individual composite character components.

Note: Backspace is always removing individual composite character components.

var caret_mid_grapheme : bool = false

Property Value

bool

Remarks

void set_caret_mid_grapheme_enabled(bool value)
bool is_caret_mid_grapheme_enabled

clear_button_enabled

If true, the LineEdit will show a clear button if text is not empty, which can be used to clear the text quickly.

var clear_button_enabled : bool = false

Property Value

bool

Remarks

void set_clear_button_enabled(bool value)
bool is_clear_button_enabled

context_menu_enabled

If true, the context menu will appear when right-clicked.

var context_menu_enabled : bool = true

Property Value

bool

Remarks

void set_context_menu_enabled(bool value)
bool is_context_menu_enabled

deselect_on_focus_loss_enabled

If true, the selected text will be deselected when focus is lost.

var deselect_on_focus_loss_enabled : bool = true

Property Value

bool

Remarks

void set_deselect_on_focus_loss_enabled(bool value)
bool is_deselect_on_focus_loss_enabled

drag_and_drop_selection_enabled

If true, allow drag and drop of selected text.

var drag_and_drop_selection_enabled : bool = true

Property Value

bool

Remarks

void set_drag_and_drop_selection_enabled(bool value)
bool is_drag_and_drop_selection_enabled

draw_control_chars

If true, control characters are displayed.

var draw_control_chars : bool = false

Property Value

bool

Remarks

void set_draw_control_chars(bool value)
bool get_draw_control_chars

editable

If false, existing text cannot be modified and new text cannot be added.

var editable : bool = true

Property Value

bool

Remarks

void set_editable(bool value)
bool is_editable

emoji_menu_enabled

If true, "Emoji and Symbols" menu is enabled.

var emoji_menu_enabled : bool = true

Property Value

bool

Remarks

void set_emoji_menu_enabled(bool value)
bool is_emoji_menu_enabled

expand_to_text_length

If true, the LineEdit width will increase to stay longer than the text. It will not compress if the text is shortened.

var expand_to_text_length : bool = false

Property Value

bool

Remarks

void set_expand_to_text_length_enabled(bool value)
bool is_expand_to_text_length_enabled

flat

If true, the LineEdit doesn't display decoration.

var flat : bool = false

Property Value

bool

Remarks

void set_flat(bool value)
bool is_flat

keep_editing_on_text_submit

If true, the LineEdit will not exit edit mode when text is submitted by pressing ui_text_submit action (by default: Enter or Kp Enter).

var keep_editing_on_text_submit : bool = false

Property Value

bool

Remarks

void set_keep_editing_on_text_submit(bool value)
bool is_editing_kept_on_text_submit

language

Language code used for line-breaking and text shaping algorithms. If left empty, current locale is used instead.

var language : String = ""

Property Value

String

Remarks

void set_language(String value)
String get_language

max_length

Maximum number of characters that can be entered inside the LineEdit. If 0, there is no limit.

When a limit is defined, characters that would exceed max_length are truncated. This happens both for existing text contents when setting the max length, or for new text inserted in the LineEdit, including pasting.

If any input text is truncated, the LineEdit.text_change_rejected signal is emitted with the truncated substring as parameter:

gdscript
C#

text = "Hello world"
max_length = 5
# `text` becomes "Hello".
max_length = 10
text += " goodbye"
# `text` becomes "Hello good".
# `text_change_rejected` is emitted with "bye" as parameter.

Text = "Hello world";
MaxLength = 5;
// `Text` becomes "Hello".
MaxLength = 10;
Text += " goodbye";
// `Text` becomes "Hello good".
// `text_change_rejected` is emitted with "bye" as parameter.

var max_length : int = 0

Property Value

int

Remarks

void set_max_length(int value)
int get_max_length

middle_mouse_paste_enabled

If false, using middle mouse button to paste clipboard will be disabled.

Note: This method is only implemented on Linux.

var middle_mouse_paste_enabled : bool = true

Property Value

bool

Remarks

void set_middle_mouse_paste_enabled(bool value)
bool is_middle_mouse_paste_enabled

placeholder_text

Text shown when the LineEdit is empty. It is not the LineEdit's default value (see text).

var placeholder_text : String = ""

Property Value

String

Remarks

void set_placeholder(String value)
String get_placeholder

right_icon

Sets the icon that will appear in the right end of the LineEdit if there's no text, or always, if clear_button_enabled is set to false.

var right_icon : Texture2D

Property Value

Texture2D

Remarks

void set_right_icon(Texture2D value)
Texture2D get_right_icon

secret

If true, every character is replaced with the secret character (see secret_character).

var secret : bool = false

Property Value

bool

Remarks

void set_secret(bool value)
bool is_secret

secret_character

The character to use to mask secret input. Only a single character can be used as the secret character. If it is longer than one character, only the first one will be used. If it is empty, a space will be used instead.

var secret_character : String = "•"

Property Value

String

Remarks

void set_secret_character(String value)
String get_secret_character

select_all_on_focus

If true, the LineEdit will select the whole text when it gains focus.

var select_all_on_focus : bool = false

Property Value

bool

Remarks

void set_select_all_on_focus(bool value)
bool is_select_all_on_focus

selecting_enabled

If false, it's impossible to select the text using mouse nor keyboard.

var selecting_enabled : bool = true

Property Value

bool

Remarks

void set_selecting_enabled(bool value)
bool is_selecting_enabled

shortcut_keys_enabled

If true, shortcut keys for context menu items are enabled, even if the context menu is disabled.

var shortcut_keys_enabled : bool = true

Property Value

bool

Remarks

void set_shortcut_keys_enabled(bool value)
bool is_shortcut_keys_enabled

structured_text_bidi_override

Set BiDi algorithm override for the structured text.

var structured_text_bidi_override : int = 0

Property Value

int

Remarks

void set_structured_text_bidi_override(int value)
int get_structured_text_bidi_override

structured_text_bidi_override_options

Set additional options for BiDi override.

var structured_text_bidi_override_options : Array = []

Property Value

Array

Remarks

void set_structured_text_bidi_override_options(Array value)
Array get_structured_text_bidi_override_options

text

String value of the LineEdit.

Note: Changing text using this property won't emit the LineEdit.text_changed signal.

var text : String = ""

Property Value

String

Remarks

void set_text(String value)
String get_text

text_direction

Base text writing direction.

var text_direction : int = 0

Property Value

int

Remarks

void set_text_direction(int value)
int get_text_direction

virtual_keyboard_enabled

If true, the native virtual keyboard is shown when focused on platforms that support it.

var virtual_keyboard_enabled : bool = true

Property Value

bool

Remarks

void set_virtual_keyboard_enabled(bool value)
bool is_virtual_keyboard_enabled

virtual_keyboard_type

Specifies the type of virtual keyboard to show.

var virtual_keyboard_type : int = 0

Property Value

int

Remarks

void set_virtual_keyboard_type(int value)
int get_virtual_keyboard_type

clear

Theme Property

Texture for the clear button. See clear_button_enabled.

Texture2D clear

Property Value

Texture2D

caret_color

Theme Property

Color of the LineEdit's caret (text cursor). This can be set to a fully transparent color to hide the caret entirely.

 = ``Color(0.95, 0.95, 0.95, 1)``

Property Value

Color

clear_button_color

Theme Property

Color used as default tint for the clear button.

 = ``Color(0.875, 0.875, 0.875, 1)``

Property Value

Color

clear_button_color_pressed

Theme Property

Color used for the clear button when it's pressed.

 = ``Color(1, 1, 1, 1)``

Property Value

Color

font_color

Theme Property

Default font color.

 = ``Color(0.875, 0.875, 0.875, 1)``

Property Value

Color

font_outline_color

Theme Property

The tint of text outline of the LineEdit.

 = ``Color(0, 0, 0, 1)``

Property Value

Color

font_placeholder_color

Theme Property

Font color for placeholder_text.

 = ``Color(0.875, 0.875, 0.875, 0.6)``

Property Value

Color

font_selected_color

Theme Property

Font color for selected text (inside the selection rectangle).

 = ``Color(1, 1, 1, 1)``

Property Value

Color

font_uneditable_color

Theme Property

Font color when editing is disabled.

 = ``Color(0.875, 0.875, 0.875, 0.5)``

Property Value

Color

selection_color

Theme Property

Color of the selection rectangle.

 = ``Color(0.5, 0.5, 0.5, 1)``

Property Value

Color

caret_width

Theme Property

The caret's width in pixels. Greater values can be used to improve accessibility by ensuring the caret is easily visible, or to ensure consistency with a large font size.

 = ``1``

Property Value

int

minimum_character_width

Theme Property

Minimum horizontal space for the text (not counting the clear button and content margins). This value is measured in count of 'M' characters (i.e. this number of 'M' characters can be displayed without scrolling).

 = ``4``

Property Value

int

outline_size

Theme Property

The size of the text outline.

Note: If using a font with multichannel_signed_distance_field enabled, its msdf_pixel_range must be set to at least twice the value of outline_size for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.

 = ``0``

Property Value

int

font

Theme Property

Font used for the text.

Font font

Property Value

Font

font_size

Theme Property

Font size of the LineEdit's text.

int font_size

Property Value

int

clear

Theme Property

Texture for the clear button. See clear_button_enabled.

Texture2D clear

Property Value

Texture2D

focus

Theme Property

Background used when LineEdit has GUI focus. The focus StyleBox is displayed over the base StyleBox, so a partially transparent StyleBox should be used to ensure the base StyleBox remains visible. A StyleBox that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a StyleBoxEmpty resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.

StyleBox focus

Property Value

StyleBox

normal

Theme Property

Default background for the LineEdit.

StyleBox normal

Property Value

StyleBox

read_only

Theme Property

Background used when LineEdit is in read-only mode (editable is set to false).

StyleBox read_only

Property Value

StyleBox

Methods

apply_ime

Applies text from the Input Method Editor (IME) and closes the IME if it is open.

void apply_ime

cancel_ime

Closes the Input Method Editor (IME) if it is open. Any text in the IME will be lost.

void cancel_ime

delete_char_at_caret

Deletes one character at the caret's current position (equivalent to pressing Delete).

void delete_char_at_caret

delete_text(int, int)

Deletes a section of the text going from position from_column to to_column. Both parameters should be within the text's length.

void delete_text(int from_column, int to_column)

Parameters

from_column int
to_column int

deselect

Clears the current selection.

void deselect

edit

Allows entering edit mode whether the LineEdit is focused or not.

get_menu

Qualifiers: const

Returns the PopupMenu of this LineEdit. By default, this menu is displayed when right-clicking on the LineEdit.

You can add custom menu items or remove standard ones. Make sure your IDs don't conflict with the standard ones (see MenuItems). For example:

gdscript
C#

func _ready():
    var menu = get_menu()
    # Remove all items after "Redo".
    menu.item_count = menu.get_item_index(MENU_REDO) + 1
    # Add custom items.
    menu.add_separator()
    menu.add_item("Insert Date", MENU_MAX + 1)
    # Connect callback.
    menu.id_pressed.connect(_on_item_pressed)

func _on_item_pressed(id):
    if id == MENU_MAX + 1:
        insert_text_at_caret(Time.get_date_string_from_system())

public override void _Ready()
{
    var menu = GetMenu();
    // Remove all items after "Redo".
    menu.ItemCount = menu.GetItemIndex(LineEdit.MenuItems.Redo) + 1;
    // Add custom items.
    menu.AddSeparator();
    menu.AddItem("Insert Date", LineEdit.MenuItems.Max + 1);
    // Add event handler.
    menu.IdPressed += OnItemPressed;
}

public void OnItemPressed(int id)
{
    if (id == LineEdit.MenuItems.Max + 1)
    {
        InsertTextAtCaret(Time.GetDateStringFromSystem());

    }

}

Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their visible property.

PopupMenu get_menu

get_scroll_offset

Qualifiers: const

Returns the scroll offset due to caret_column, as a number of characters.

float get_scroll_offset

get_selected_text

Returns the text inside the selection.

String get_selected_text

get_selection_from_column

Qualifiers: const

Returns the selection begin column.

int get_selection_from_column

get_selection_to_column

Qualifiers: const

Returns the selection end column.

int get_selection_to_column

has_ime_text

Qualifiers: const

Returns true if the user has text in the Input Method Editor (IME).

bool has_ime_text

has_redo

Qualifiers: const

Returns true if a "redo" action is available.

bool has_redo

has_selection

Qualifiers: const

Returns true if the user has selected text.

bool has_selection

has_undo

Qualifiers: const

Returns true if an "undo" action is available.

bool has_undo

insert_text_at_caret(String)

Inserts text at the caret. If the resulting value is longer than max_length, nothing happens.

void insert_text_at_caret(String text)

Parameters

text String

is_editing

Qualifiers: const

Returns whether the LineEdit is being edited.

bool is_editing

is_menu_visible

Qualifiers: const

Returns whether the menu is visible. Use this instead of get_menu().visible to improve performance (so the creation of the menu is avoided).

bool is_menu_visible

menu_option(int)

Executes a given action as defined in the MenuItems enum.

void menu_option(int option)

Parameters

option int

select(int, int)

Selects characters inside LineEdit between from and to. By default, from is at the beginning and to at the end.

gdscript
C#

text = "Welcome"
select() # Will select "Welcome".
select(4) # Will select "ome".
select(2, 5) # Will select "lco".

Text = "Welcome";
Select(); // Will select "Welcome".
Select(4); // Will select "ome".
Select(2, 5); // Will select "lco".

void select(int from, int to)

Parameters

from int
to int

select_all

Selects the whole String.

void select_all

unedit

Allows exiting edit mode while preserving focus.

void unedit

Events

editing_toggled(bool)

Emitted when the LineEdit switches in or out of edit mode.

signal editing_toggled(bool toggled_on)

Parameters

toggled_on bool

text_change_rejected(String)

Emitted when appending text that overflows the max_length. The appended text is truncated to fit max_length, and the part that couldn't fit is passed as the rejected_substring argument.

signal text_change_rejected(String rejected_substring)

Parameters

rejected_substring String

text_changed(String)

Emitted when the text changes.

signal text_changed(String new_text)

Parameters

new_text String

text_submitted(String)

Emitted when the user presses the ui_text_submit action (by default: Enter or Kp Enter) while the LineEdit has focus.

signal text_submitted(String new_text)

Parameters

new_text String

Table of Contents

Class LineEdit

Remarks

Properties

alignment

Property Value

Remarks

caret_blink

Property Value

Remarks

caret_blink_interval

Property Value

Remarks

caret_column

Property Value

Remarks

caret_force_displayed

Property Value

Remarks

caret_mid_grapheme

Property Value

Remarks

clear_button_enabled

Property Value

Remarks

context_menu_enabled

Property Value

Remarks

deselect_on_focus_loss_enabled

Property Value

Remarks

drag_and_drop_selection_enabled

Property Value

Remarks

draw_control_chars

Property Value

Remarks

editable

Property Value

Remarks

emoji_menu_enabled

Property Value

Remarks

expand_to_text_length

Property Value

Remarks

flat

Property Value

Remarks

keep_editing_on_text_submit

Property Value

Remarks

language

Property Value

Remarks

max_length

Property Value

Remarks

middle_mouse_paste_enabled

Property Value

Remarks

placeholder_text

Property Value

Remarks

right_icon

Property Value

Remarks

secret

Property Value

Remarks

secret_character

Property Value

Remarks

select_all_on_focus

Property Value

Remarks

selecting_enabled

Property Value

Remarks

shortcut_keys_enabled