Skip to main content

​
TextField

A text field lets the user enter text, either with hardware keyboard or with an onscreen keyboard.

​
Properties

​
Basic Properties

​
value
str
default:""
Current value of the TextField.
​
label
str | Control
Optional text that describes the input field. When the input field is empty and unfocused, the label is displayed on top of the input field. When the input field receives focus (or if the field is non-empty) the label moves above the input field.
​
hint_text
str
Text that suggests what sort of input the field accepts. Displayed on top of the input when it’s empty and either the label is None or the input has focus.
​
helper
str | Control
Text that provides context about the input’s value, such as how the value will be used. Displayed below the input decorator. If a non-null error value is specified then the helper text is not shown.
​
icon
IconData | Icon
The icon to show before the input field and outside of the decoration’s container.

​
Text Configuration

​
text_size
Number
Text size in virtual pixels.
​
text_style
TextStyle
The TextStyle to use for the text being edited.
​
text_align
TextAlign
default:"TextAlign.LEFT"
How the text should be aligned horizontally.
​
text_vertical_align
VerticalAlignment | Number
default:"VerticalAlignment.CENTER"
Defines how the text should be aligned vertically. Value can either be a number ranging from -1.0 (topmost location) to 1.0 (bottommost location) or of type VerticalAlignment.

​
Input Behavior

​
keyboard_type
KeyboardType
default:"KeyboardType.TEXT"
The type of keyboard to use for editing the text. Options include: TEXT, MULTILINE, NUMBER, PHONE, DATETIME, EMAIL, URL, VISIBLE_PASSWORD, NAME, STREET_ADDRESS, WEB_SEARCH, TWITTER.
​
multiline
bool
default:"False"
Whether this field can contain multiple lines of text.
​
min_lines
int
default:"1"
The minimum number of lines to occupy when the content spans fewer lines. This affects the height of the field itself and does not limit the number of lines that can be entered.Must be positive and not exceed max_lines when both are set.
​
max_lines
int
default:"1"
The maximum number of lines to show at one time, wrapping if necessary. If this is 1, the text will not wrap, but will scroll horizontally instead.Must be positive and not less than min_lines.
​
max_length
int
Limits a maximum number of characters that can be entered into TextField. Must be either -1 or a positive integer.
​
password
bool
default:"False"
Whether to hide the text being edited.
​
can_reveal_password
bool
default:"False"
Displays a toggle icon button that allows revealing the entered password. Is shown if both password and can_reveal_password are True. The icon is displayed in the same location as suffix and in case both are provided, then the suffix is not shown.
​
read_only
bool
default:"False"
Whether the text can be changed. When this is set to True, the text cannot be modified by any shortcut or keyboard operation. The text is still selectable.
​
shift_enter
bool
default:"False"
Changes the behavior of Enter button in multiline TextField to be chat-like, i.e. new line can be added with Shift+Enter and pressing just Enter fires on_submit event.
​
ignore_up_down_keys
bool
default:"False"
Whether to intercept Arrow-Up and Arrow-Down when this field has focus. When set to True, pressing those keys does not move the caret to the beginning or end of the text respectively.

​
Text Formatting

​
capitalization
TextCapitalization
default:"TextCapitalization.NONE"
Enables automatic on-the-fly capitalization of entered text. Options: CHARACTERS, WORDS, SENTENCES, NONE.
​
autocorrect
bool
default:"True"
Whether to enable autocorrection.
​
enable_suggestions
bool
default:"True"
Whether to show input suggestions as the user types. This flag only affects Android. On iOS, suggestions are tied directly to autocorrect.
​
smart_dashes_type
bool
default:"True"
Whether to allow the platform to automatically format dashes. This flag only affects iOS versions 11 and above.
​
smart_quotes_type
bool
default:"True"
Whether to allow the platform to automatically format quotes. This flag only affects iOS.

​
Input Filtering

​
input_filter
InputFilter
Provides as-you-type filtering/validation. Similar to the on_change callback, the input filters are not applied when the content of the field is changed programmatically.

​
Selection

​
selection
TextSelection
Represents the current text selection or caret position in the field. Setting this property visually updates the field’s selection and triggers the on_selection_change event. To ensure the selection is visible and the event is fired, the text field must be focused.

​
Cursor Styling

​
show_cursor
bool
default:"True"
Whether the field’s cursor is to be shown.
​
cursor_color
ColorValue
The color of TextField cursor.
​
cursor_width
Number
default:"2.0"
Sets cursor width.
​
cursor_height
Number
Sets cursor height.
​
cursor_radius
Number
Sets cursor radius.
​
selection_color
ColorValue
The color of TextField selection.

​
Visual Styling

​
color
ColorValue
Text color.
​
bgcolor
ColorValue
TextField background color. Will not be visible if filled is False.
​
border
InputBorder
default:"InputBorder.OUTLINE"
Border around input. Options: NONE, OUTLINE, UNDERLINE.
​
border_radius
BorderRadiusValue
The border radius of the input decoration.
​
border_width
Number
default:"1"
The width of the border in virtual pixels. Set to 0 to completely remove the border.
​
border_color
ColorValue
The border color. Set to Colors.TRANSPARENT to invisible/hide the border.
​
focused_color
ColorValue
The text’s color when focused.
​
focused_bgcolor
ColorValue
Background color in focused state. Will not be visible if filled is False.
​
focused_border_width
Number
Border width in focused state.
​
focused_border_color
ColorValue
Border color in focused state.
​
filled
bool
If True the decoration’s container is filled with theme fill_color. If None (default), it is implicitly set to True when at least one color property is not None.
​
fill_color
ColorValue
Background color of TextField. Will not be visible if filled is False.
​
hover_color
ColorValue
Background color of TextField when hovered. Will not be visible if filled is False.

​
Decorations

​
prefix
str | Control
A Control to place on the line before the input. This can be used to add padding or a custom control in front of the input.
​
prefix_icon
IconData | Icon
An icon that appears before the editable part of the text field, within the decoration’s container.
​
suffix
str | Control
A Control to place on the line after the input. This can be used to add padding or a custom control after the input.
​
suffix_icon
IconData | Icon
An icon that appears after the editable part of the text field and after the suffix, within the decoration’s container.
​
counter
str | Control
A Control to place below the line as a character count. If None or an empty string then nothing will appear in the counter’s location.
​
error
str | Control
Text that appears below the input border. If non-null, the border’s color animates to red and the helper is not shown.

​
Padding and Layout

​
content_padding
PaddingValue
The padding for the input decoration’s container.
​
dense
bool
Whether this control is part of a dense form (i.e., uses less vertical space).

​
Other Properties

​
autofocus
bool
default:"False"
True if the control will be selected as the initial focus. If there is more than one control on a page with autofocus set, then the first one added to the page will get focus.
​
autofill_hints
AutofillHint | list[AutofillHint]
Helps the autofill service identify the type of this text input.
​
clip_behavior
ClipBehavior
default:"ClipBehavior.HARD_EDGE"
Defines how the content is clipped.
​
mouse_cursor
MouseCursor
The mouse cursor to use when hovering over this control.

​
Events

​
on_change
ControlEventHandler
Called when the typed input for the TextField has changed.
​
on_selection_change
EventHandler[TextSelectionChangeEvent]
Called when the text selection or caret position changes. This can be triggered either by user interaction or programmatically through the selection property.
​
on_submit
ControlEventHandler
Called when user presses ENTER while focus is on TextField.
​
on_focus
ControlEventHandler
Called when the control has received focus.
​
on_blur
ControlEventHandler
Called when the control has lost focus.

​
Methods

​
focus()
async
Request focus for this control.Example:
async def main(page: ft.Page):
    page.add(ctf := ft.TextField())
    await ctf.focus()

​
Helper Classes

​
InputFilter

An input filter that uses a regular expression to allow or deny certain patterns in the input. Properties:
  • regex_string (str): A regular expression pattern for the filter. Recommended to use raw strings (e.g., r"pattern").
  • allow (bool): Whether to allow or deny/block the matched patterns. Default: True.
  • replacement_string (str): A string used to replace banned/denied patterns. Default: empty string.
  • multiline (bool): Whether the regexp matches multiple lines. Default: False.
  • case_sensitive (bool): Whether the regular expression is case sensitive. Default: True.
  • unicode (bool): Whether the regular expression uses Unicode mode. Default: False.
  • dot_all (bool): Whether "." matches line terminators. Default: False.

​
NumbersOnlyInputFilter

A pre-configured filter that allows only numbers. 
ft.TextField(input_filter=ft.NumbersOnlyInputFilter())

​
TextOnlyInputFilter

A pre-configured filter that allows only text (letters). 
ft.TextField(input_filter=ft.TextOnlyInputFilter())

​
Example

import flet as ft

def main(page: ft.Page):
    def on_text_change(e):
        print(f"Text changed: {e.control.value}")
    
    def on_submit(e):
        print(f"Submitted: {e.control.value}")
    
    page.add(
        ft.TextField(
            label="Name",
            hint_text="Jane Doe",
            on_change=on_text_change,
            on_submit=on_submit
        ),
        ft.TextField(
            label="Password",
            password=True,
            can_reveal_password=True
        ),
        ft.TextField(
            label="Multiline",
            multiline=True,
            min_lines=3,
            max_lines=5
        ),
        ft.TextField(
            label="Email",
            keyboard_type=ft.KeyboardType.EMAIL,
            autofill_hints=ft.AutofillHint.EMAIL
        ),
        ft.TextField(
            label="Numbers only",
            input_filter=ft.NumbersOnlyInputFilter()
        )
    )

ft.app(target=main)

Build docs developers (and LLMs) love

Get started for freeTalk to us