Text fields

See also

Material Design spec, Text fields

Text fields let users enter text into a UI.

• Make sure text fields look interactive

• Two types: filled and outlined

• The text field’s state (blank, with input, error, etc) should be visible at a glance

• Keep labels and error messages brief and easy to act on

• Text fields commonly appear in forms and dialogs

1. Filled text field

2. Outlined text field

Usage

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "magnify"

    MDTextFieldHintText:
        text: "Hint text"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "persistent"

    MDTextFieldTrailingIcon:
        icon: "information"

    MDTextFieldMaxLengthText:
        max_text_length: 10

Anatomy

Available types of text fields

Filled mode

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

Outlined mode

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "outlined"

Example

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.backgroundColor

    MDTextField:
        mode: "outlined"
        size_hint_x: None
        width: "240dp"
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTextFieldLeadingIcon:
            icon: "account"

        MDTextFieldHintText:
            text: "Outlined"

        MDTextFieldHelperText:
            text: "Helper text"
            mode: "persistent"

        MDTextFieldTrailingIcon:
            icon: "information"

        MDTextFieldMaxLengthText:
            max_text_length: 10
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

API break

1.2.0 version

MDTextField:
    mode: "rectangle"
    hint_text: "Hint text"
    helper_text: "Helper text"
    helper_text_mode: "persistent"
    max_text_length: 10
    icon_right: "information"

2.0.0 version

Note

The text field with the round type was removed in version 2.0.0.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "outlined"

    MDTextFieldLeadingIcon:
        icon: "phone"

    MDTextFieldTrailingIcon:
        icon: "information"

    MDTextFieldHintText:
        text: "Hint text"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "persistent"

    MDTextFieldMaxLengthText:
        max_text_length: 10

API - kivymd.uix.textfield.textfield

class kivymd.uix.textfield.textfield.AutoFormatTelephoneNumber

Implements automatic formatting of the text entered in the text field according to the mask, for example ‘+38 (###) ### ## ##’.

Warning

This class has not yet been implemented and it is not recommended to use it yet.

isnumeric(value) → bool

do_backspace(*args) → None

Do backspace operation from the current cursor position.

field_filter(value, boolean) → None

format(value) → None

class kivymd.uix.textfield.textfield.Validator

Container class for various validation methods.

datetime_date

The last valid date as a <class ‘datetime.date’> object.

datetime_date is an ObjectProperty and defaults to None.

date_interval

The date interval that is valid for input. Can be entered as <class ‘datetime.date’> objects or a string format. Both values or just one value can be entered.

In string format, must follow the current date_format. Example: Given date_format -> “mm/dd/yyyy” Input examples -> “12/31/1900”, “12/31/2100” or “12/31/1900”, None.

date_interval is an ListProperty and defaults to [None, None].

date_format

Format of date strings that will be entered. Available options are: ‘dd/mm/yyyy’, ‘mm/dd/yyyy’, ‘yyyy/mm/dd’.

date_format is an OptionProperty and defaults to None.

is_email_valid(text: str) → bool

Checks the validity of the email.

is_time_valid(text: str) → bool

Checks the validity of the time.

is_date_valid(text: str) → bool

Checks the validity of the date.

on_date_interval(*args) → None

Default event handler for date_interval input.

class kivymd.uix.textfield.textfield.BaseTextFieldLabel(*args, **kwargs)

Base texture for MDTextField class (helper text, max length, hint text).

For more information, see in the MDLabel class documentation.

Added in version 2.0.0.

text_color_normal

Text color in (r, g, b, a) or string format when text field is out of focus.

Added in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_color_normal to text_color_normal.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldHintText:
        text: "Hint text color normal"
        text_color_normal: "brown"

text_color_normal is an ColorProperty and defaults to None.

text_color_focus

Text color in (r, g, b, a) or string format when the text field has focus.

Added in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_color_focus to text_color_focus.

Declarative KV styleDeclarative Python style

MDTextField:

    MDTextFieldHelperText:
        text: "Helper text color focus"
        text_color_focus: "brown"

text_color_focus is an ColorProperty and defaults to None.

class kivymd.uix.textfield.textfield.MDTextFieldHelperText(*args, **kwargs)

Implements the helper text label.

For more information, see in the BaseTextFieldLabel class documentation.

Added in version 2.0.0.

mode

Helper text mode. Available options are: ‘on_error’, ‘persistent’, ‘on_focus’.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_mode to mode.

On focus

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "on_focus"

On error

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "on_error"

    MDTextFieldMaxLengthText:
        max_text_length: 5

Persistent

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldHelperText:
        text: "Helper text"
        mode: "persistent"

mode is an OptionProperty and defaults to ‘on_focus’.

class kivymd.uix.textfield.textfield.MDTextFieldMaxLengthText(*args, **kwargs)

Implements the max length text label.

For more information, see in the BaseTextFieldLabel class documentation.

Added in version 2.0.0.

max_text_length

Maximum allowed value of characters in a text field.

Changed in version 2.0.0: The property was moved from class:~MDTextField.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldMaxLengthText:
        max_text_length: 10

max_text_length is an NumericProperty and defaults to None.

class kivymd.uix.textfield.textfield.MDTextFieldHintText(*args, **kwargs)

Implements the hint text label.

For more information, see in the BaseTextFieldLabel class documentation.

Added in version 2.0.0.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldHintText:
        text: "Hint text"

class kivymd.uix.textfield.textfield.BaseTextFieldIcon(*args, **kwargs)

Base texture for MDTextField class (helper text, max length, hint text).

For more information, see in the MDIcon class documentation.

Changed in version 2.0.0.

icon_color_normal

Icon color in (r, g, b, a) or string format when text field is out of focus.

Added in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from icon_right_color_normal/icon_left_color_normal to icon_color_normal.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "phone"
        theme_icon_color: "Custom"
        icon_color_normal: "lightgreen"

    MDTextFieldHintText:
        text: "Leading icon color normal"

icon_color_normal is an ColorProperty and defaults to None.

icon_color_focus

Icon color in (r, g, b, a) or string format when the text field has focus.

Added in version 1.0.0.

Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from icon_right_color_focus/icon_left_color_focus ` to `icon_color_focus.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "phone"
        theme_icon_color: "Custom"
        icon_color_focus: "lightgreen"

    MDTextFieldHintText:
        text: "Leading icon color focus"

icon_color_focus is an ColorProperty and defaults to None.

on_icon_color_normal(instance: BaseTextFieldIcon | MDTextFieldTrailingIcon, value: list | str)

Called when the icon_color_normal property of the icon is changed.

If the associated text field is set, this method triggers an update to the icon’s color appearance, ensuring that the correct color is used based on the focus state of the text field.

Typically used to visually reflect property changes in real time in response to user interaction or theme updates.

Parameters:

• instance – The instance of BaseTextFieldIcon that had its icon_color_normal property changed.

• value – The new color value, either as a list of RGBA components or a string (e.g., a hex color or color name).

class kivymd.uix.textfield.textfield.MDTextFieldLeadingIcon(*args, **kwargs)

Implements the leading icon.

For more information, see in the BaseTextFieldIcon class documentation.

Added in version 2.0.0.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldLeadingIcon:
        icon: "phone"

    MDTextFieldHintText:
        text: "Field with leading icon"

class kivymd.uix.textfield.textfield.MDTextFieldTrailingIcon(*args, **kwargs)

Implements the trailing icon.

For more information, see in the BaseTextFieldIcon class documentation.

Added in version 2.0.0.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"

    MDTextFieldTrailingIcon:
        icon: "phone"

    MDTextFieldHintText:
        text: "Field with trailing icon"

class kivymd.uix.textfield.textfield.MDTextField(*args, **kwargs)

Textfield class.

For more information, see in the DeclarativeBehavior and BackgroundColorBehavior and ThemableBehavior and TextInput and Validator and AutoFormatTelephoneNumber and StateLayerBehavior classes documentation.

font_style

Name of the style for the input text.

Added in version 2.0.0.

See also

Font style names

font_style is an StringProperty and defaults to ‘Body’.

role

Role of font style.

Added in version 2.0.0.

See also

Font style roles

role is an StringProperty and defaults to ‘large’.

mode

Text field mode. Available options are: ‘outlined’, ‘filled’.

mode is an OptionProperty and defaults to ‘outlined’.

error_color

Error color in (r, g, b, a) or string format for required = True or when the text field is in error state.

error_color is an ColorProperty and defaults to None.

error

If True, then the text field goes into error mode.

error is an BooleanProperty and defaults to False.

text_color_normal

Text color in (r, g, b, a) or string format when text field is out of focus.

Added in version 1.0.0.

Declarative KV styleDeclarative Python style

MDTextField:
    theme_text_color: "Custom"
    text_color_normal: "green"
    text: "Text color normal"

text_color_normal is an ColorProperty and defaults to None.

text_color_focus

Text color in (r, g, b, a) or string format when text field has focus.

Added in version 1.0.0.

Declarative KV styleDeclarative Python style

MDTextField:
    theme_text_color: "Custom"
    text_color_focus: "green"
    text: "Text color focus"

text_color_focus is an ColorProperty and defaults to None.

radius

The corner radius for a text field in filled/outlined mode.

radius is a VariableListProperty and defaults to [dp(4), dp(4), 0, 0].

required

Required text. If True then the text field requires text.

required is an BooleanProperty and defaults to False.

line_color_normal

Line color normal (active indicator) in (r, g, b, a) or string format.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"
    theme_line_color: "Custom"
    line_color_normal: "green"

    MDTextFieldHelperText:
        text: "Line color normal"
        mode: "persistent"

line_color_normal is an ColorProperty and defaults to None.

line_color_focus

Line color focus (active indicator) in (r, g, b, a) or string format.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"
    theme_line_color: "Custom"
    line_color_focus: "green"

    MDTextFieldHelperText:
        text: "Line color focus"
        mode: "persistent"

line_color_focus is an ColorProperty and defaults to None.

fill_color_normal

Fill background color in (r, g, b, a) or string format in ‘fill’ mode when] text field is out of focus.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"
    theme_bg_color: "Custom"
    fill_color_normal: 0, 1, 0, .2

    MDTextFieldHelperText:
        text: "Fill color normal"
        mode: "persistent"

fill_color_normal is an ColorProperty and defaults to None.

fill_color_focus

Fill background color in (r, g, b, a) or string format in ‘fill’ mode when the text field has focus.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"
    theme_bg_color: "Custom"
    fill_color_focus: 0, 1, 0, .2

    MDTextFieldHelperText:
        text: "Fill color focus"
        mode: "persistent"

fill_color_focus is an ColorProperty and defaults to None.

max_height

Maximum height of the text box when multiline = True.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"
    max_height: "200dp"
    multiline: True

    MDTextFieldHelperText:
        text: "multiline=True"
        mode: "persistent"

max_height is a NumericProperty and defaults to 0.

phone_mask

This property has not yet been implemented and it is not recommended to use it yet.

phone_mask is a StringProperty and defaults to ‘’.

validator

The type of text field for entering Email, time, etc. Automatically sets the type of the text field as “error” if the user input does not match any of the set validation types. Available options are: ‘date’, ‘email’, ‘time’.

When using ‘date’, date_format must be defined.

Added in version 1.1.0.

Declarative KV styleDeclarative Python style

MDTextField:
    mode: "filled"
    validator: "email"

    MDTextFieldHintText:
        text: "Email"

    MDTextFieldHelperText:
        text: "user@gmail.com"
        mode: "persistent"

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        orientation: "vertical"
        spacing: "28dp"
        adaptive_height: True
        size_hint_x: .8
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy without limits"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "mm/dd/yyyy"

            MDTextFieldHintText:
                text: "Date mm/dd/yyyy without limits"

            MDTextFieldHelperText:
                text: "Enter a valid mm/dd/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "yyyy/mm/dd"

            MDTextFieldHintText:
                text: "Date yyyy/mm/dd without limits"

            MDTextFieldHelperText:
                text: "Enter a valid yyyy/mm/dd date"

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: "01/01/1900", "01/01/2100"

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy in [01/01/1900, 01/01/2100] interval"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: "01/01/1900", None

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy in [01/01/1900, None] interval"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"

        MDTextField:
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: None, "01/01/2100"

            MDTextFieldHintText:
                text: "Date dd/mm/yyyy in [None, 01/01/2100] interval"

            MDTextFieldHelperText:
                text: "Enter a valid dd/mm/yyyy date"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

validator is an OptionProperty and defaults to None.

update_colors(theme_manager: kivymd.theming.ThemeManager, theme_color: str) → None

Fired when the primary_palette or theme_style value changes.

add_widget(widget, index=0, canvas=None)

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

Added in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

set_texture_color(texture, canvas_group, color: list, error: bool = False) → None

Animates the color of the leading/trailing icons/hint/helper/max length text.

get_adjusted_pos_max_length_label() → tuple

Calculates the position of the max length label.

Returns:

tuple: (x, y) coordinates for positioning the max length label.

get_adjusted_pos_helper_text_label() → tuple

Calculates the position of the helper text label based on the textfield mode.

Returns:

tuple: (x, y) coordinates for positioning the helper text label.

get_adjusted_pos_trailing_icon() → tuple

Calculates the adjusted position of the trailing icon.

Returns:

tuple: (x, y) coordinates for positioning the trailing icon.

get_adjusted_pos_leading_icon() → tuple

Calculates the adjusted position of the leading icon based on the textfield mode and icon size.

Returns:

tuple: (x, y) coordinates for positioning the leading icon.

get_adjusted_pos_hint_text_label() → tuple

Calculates the adjusted position of the hint text label based on the presence of a leading icon and whether the textfield is multiline.

Returns:

tuple: (x, y) position coordinates for the hint text label.

set_pos_hint_text(y: float, x: float) → None

Animates the x-axis width and y-axis height of the hint text.

set_hint_text_font_size() → None

Animates the font size of the hint text.

set_space_in_line(left_width: float | int, right_width: float | int) → None

Animates the length of the right line of the text field for the hint text.

set_max_text_length() → None

Fired when text is entered into a text field. Set max length text and updated max length texture.

adjust_height(*args) → None

Adjusts the height of the text field in multiline mode.

set_text(instance, text: str) → None

Fired when text is entered into a text field.

on_focus(instance, focus: bool) → None

Fired when the focus value changes.

on_disabled(instance, disabled: bool) → None

Fired when the disabled value changes.

on_error(instance, error: bool) → None

Changes the primary colors of the text box to match the error value (text field is in an error state or not).

on_height(instance, value_height: float) → None