TextField

See also

Material Design spec, Text fields

Text fields let users enter and edit text.

KivyMD provides the following field classes for use:

• MDTextField

• MDTextFieldRect

Note

MDTextField inherited from TextInput. Therefore, most parameters and all events of the TextInput class are also available in the MDTextField class.

MDTextField

MDTextField can be with helper text and without.

Without helper text mode

MDTextField:
    hint_text: "No helper text"

Helper text mode on on_focus event

MDTextField:
    hint_text: "Helper text on focus"
    helper_text: "This will disappear when you click off"
    helper_text_mode: "on_focus"

Persistent helper text mode

MDTextField:
    hint_text: "Persistent helper text"
    helper_text: "Text is always here"
    helper_text_mode: "persistent"

Helper text mode ‘on_error’

To display an error in a text field when using the helper_text_mode: "on_error" parameter, set the “error” text field parameter to True:

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDTextField:
        id: text_field_error
        hint_text: "Helper text on error (press 'Enter')"
        helper_text: "There will always be a mistake"
        helper_text_mode: "on_error"
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .5
'''


class Test(MDApp):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.screen = Builder.load_string(KV)

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        self.screen.ids.text_field_error.bind(
            on_text_validate=self.set_error_message,
            on_focus=self.set_error_message,
        )
        return self.screen

    def set_error_message(self, instance_textfield):
        self.screen.ids.text_field_error.error = True


Test().run()

Helper text mode ‘on_error’ (with required)

MDTextField:
    hint_text: "required = True"
    text: "required = True"
    required: True
    helper_text_mode: "on_error"
    helper_text: "Enter text"

Text length control

MDTextField:
    hint_text: "Max text length = 5"
    max_text_length: 5

Multi line text

MDTextField:
    multiline: True
    hint_text: "Multi-line text"

Rectangle mode

MDTextField:
    hint_text: "Rectangle mode"
    mode: "rectangle"

Fill mode

MDTextField:
    hint_text: "Fill mode"
    mode: "fill"

Round mode

MDTextField:
    hint_text: "Round mode"
    mode: "round"
    max_text_length: 15
    helper_text: "Massage"

MDTextFieldRect

Note

MDTextFieldRect inherited from TextInput. You can use all parameters and attributes of the TextInput class in the MDTextFieldRect class.

MDTextFieldRect:
    size_hint: 1, None
    height: "30dp"
    background_color: app.theme_cls.bg_normal

Warning

While there is no way to change the color of the border.

Clickable icon for MDTextField

from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.uix.relativelayout import MDRelativeLayout

KV = '''
<ClickableTextFieldRound>:
    size_hint_y: None
    height: text_field.height

    MDTextField:
        id: text_field
        hint_text: root.hint_text
        text: root.text
        password: True
        icon_left: "key-variant"

    MDIconButton:
        icon: "eye-off"
        pos_hint: {"center_y": .5}
        pos: text_field.width - self.width + dp(8), 0
        theme_text_color: "Hint"
        on_release:
            self.icon = "eye" if self.icon == "eye-off" else "eye-off"
            text_field.password = False if text_field.password is True else True


MDScreen:

    ClickableTextFieldRound:
        size_hint_x: None
        width: "300dp"
        hint_text: "Password"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class ClickableTextFieldRound(MDRelativeLayout):
    text = StringProperty()
    hint_text = StringProperty()
    # Here specify the required parameters for MDTextFieldRound:
    # [...]


class Test(MDApp):
    def build(self):
        return Builder.load_string(KV)


Test().run()

See also

See more information in the MDTextFieldRect class.

API - kivymd.uix.textfield.textfield

class kivymd.uix.textfield.textfield.MDTextFieldRect(**kwargs)

Textfield rect class.

For more information, see in the ThemableBehavior and TextInput classes documentation.

line_anim

If True, then text field shows animated line when on focus.

line_anim is an BooleanProperty and defaults to True.

get_rect_instruction(self)

get_color_instruction(self)

anim_rect(self, points, alpha)

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

Textfield class.

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

helper_text

Text for helper_text mode.

helper_text is an StringProperty and defaults to ‘’.

helper_text_mode

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

helper_text_mode is an OptionProperty and defaults to ‘none’.

max_text_length

Maximum allowed value of characters in a text field.

max_text_length is an NumericProperty and defaults to None.

required

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

required is an BooleanProperty and defaults to False.

mode

Text field mode. Available options are: ‘line’, ‘rectangle’, ‘fill’, ‘round’.

mode is an OptionProperty and defaults to ‘line’.

phone_mask

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.

New in version 1.1.0.

MDTextField:
    hint_text: "Email"
    helper_text: "user@gmail.com"
    validator: "email"

Declarative KV styleDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

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

        MDTextField:
            hint_text: "Date dd/mm/yyyy without limits"
            helper_text: "Enter a valid dd/mm/yyyy date"
            validator: "date"
            date_format: "dd/mm/yyyy"

        MDTextField:
            hint_text: "Date mm/dd/yyyy without limits"
            helper_text: "Enter a valid mm/dd/yyyy date"
            validator: "date"
            date_format: "mm/dd/yyyy"

        MDTextField:
            hint_text: "Date yyyy/mm/dd without limits"
            helper_text: "Enter a valid yyyy/mm/dd date"
            validator: "date"
            date_format: "yyyy/mm/dd"

        MDTextField:
            hint_text: "Date dd/mm/yyyy in [01/01/1900, 01/01/2100] interval"
            helper_text: "Enter a valid dd/mm/yyyy date"
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: "01/01/1900", "01/01/2100"

        MDTextField:
            hint_text: "Date dd/mm/yyyy in [01/01/1900, None] interval"
            helper_text: "Enter a valid dd/mm/yyyy date"
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: "01/01/1900", None

        MDTextField:
            hint_text: "Date dd/mm/yyyy in [None, 01/01/2100] interval"
            helper_text: "Enter a valid dd/mm/yyyy date"
            validator: "date"
            date_format: "dd/mm/yyyy"
            date_interval: None, "01/01/2100"
'''


class Test(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        return Builder.load_string(KV)


Test().run()

validator is an OptionProperty and defaults to None.

line_color_normal

Line color normal (static underline line) in (r, g, b, a) or string format.

MDTextField:
    hint_text: "line_color_normal"
    line_color_normal: "red"

line_color_normal is an ColorProperty and defaults to [0, 0, 0, 0].

line_color_focus

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

MDTextField:
    hint_text: "line_color_focus"
    line_color_focus: "red"

line_color_focus is an ColorProperty and defaults to [0, 0, 0, 0].

line_anim

If True, then text field shows animated underline when on focus.

line_anim is an BooleanProperty and defaults to True.

error_color

Error color in (r, g, b, a) or string format for required = True.

error_color is an ColorProperty and defaults to [0, 0, 0, 0].

fill_color_normal

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

fill_color_normal is an ColorProperty and defaults to [0, 0, 0, 0].

fill_color_focus

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

fill_color_focus is an ColorProperty and defaults to [0, 0, 0, 0].

active_line

Show active line or not.

active_line is an BooleanProperty and defaults to True.

error

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

error is an BooleanProperty and defaults to False.

hint_text_color_normal

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

New in version 1.0.0.

MDTextField:
    hint_text: "hint_text_color_normal"
    hint_text_color_normal: "red"

hint_text_color_normal is an ColorProperty and defaults to [0, 0, 0, 0].

hint_text_color_focus

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

New in version 1.0.0.

MDTextField:
    hint_text: "hint_text_color_focus"
    hint_text_color_focus: "red"

hint_text_color_focus is an ColorProperty and defaults to [0, 0, 0, 0].

helper_text_color_normal

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

New in version 1.0.0.

MDTextField:
    helper_text: "helper_text_color_normal"
    helper_text_mode: "persistent"
    helper_text_color_normal: "red"

helper_text_color_normal is an ColorProperty and defaults to [0, 0, 0, 0].

helper_text_color_focus

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

New in version 1.0.0.

MDTextField:
    helper_text: "helper_text_color_focus"
    helper_text_mode: "persistent"
    helper_text_color_focus: "red"

helper_text_color_focus is an ColorProperty and defaults to [0, 0, 0, 0].

icon_right_color_normal

Color in (r, g, b, a) or string format of right icon when text field is out of focus.

New in version 1.0.0.

MDTextField:
    icon_right: "language-python"
    hint_text: "icon_right_color_normal"
    icon_right_color_normal: "red"

icon_right_color_normal is an ColorProperty and defaults to [0, 0, 0, 0].

icon_right_color_focus

Color in (r, g, b, a) or string format of right icon when the text field has focus.

New in version 1.0.0.

MDTextField:
    icon_right: "language-python"
    hint_text: "icon_right_color_focus"
    icon_right_color_focus: "red"

icon_right_color_focus is an ColorProperty and defaults to [0, 0, 0, 0].

icon_left_color_normal

Color in (r, g, b, a) or string format of right icon when text field is out of focus.

New in version 1.0.0.

icon_left_color_normal is an ColorProperty and defaults to [0, 0, 0, 0].

icon_left_color_focus

Color in (r, g, b, a) or string format of right icon when the text field has focus.

New in version 1.0.0.

icon_left_color_focus is an ColorProperty and defaults to [0, 0, 0, 0].

max_length_text_color

Text color in (r, g, b, a) or string format of the maximum length of characters to be input.

New in version 1.0.0.

MDTextField:
    hint_text: "max_length_text_color"
    max_length_text_color: "red"
    max_text_length: 5

max_length_text_color is an ColorProperty and defaults to [0, 0, 0, 0].

icon_right

Right icon texture.

Note

It’s just a texture. It has no press/touch events.

icon_right is an StringProperty and defaults to ‘’.

icon_left

Left icon texture.

New in version 1.0.0.

Note

It’s just a texture. It has no press/touch events. Also note that you cannot use the left and right icons at the same time yet.

icon_left is an StringProperty and defaults to ‘’.

text_color_normal

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

New in version 1.0.0.

MDTextField:
    hint_text: "text_color_normal"
    text_color_normal: "red"

text_color_normal is an ColorProperty and defaults to [0, 0, 0, 0].

text_color_focus

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

New in version 1.0.0.

MDTextField:
    hint_text: "text_color_focus"
    text_color_focus: "red"

text_color_focus is an ColorProperty and defaults to [0, 0, 0, 0].

font_size

Font size of the text in pixels.

font_size is a NumericProperty and defaults to ’16sp’.

max_height

Maximum height of the text box when multiline = True.

MDTextField:
    size_hint_x: .5
    hint_text: "multiline=True"
    max_height: "200dp"
    mode: "fill"
    fill_color: 0, 0, 0, .4
    multiline: True
    pos_hint: {"center_x": .5, "center_y": .5}

max_height is a NumericProperty and defaults to 0.

radius

The corner radius for a text field in fill/rectangle mode.

radius is a ListProperty and defaults to [10, 10, 0, 0].

font_name_helper_text

Font name for helper text.

font_name_helper_text is an StringProperty and defaults to ‘Roboto’.

font_name_hint_text

Font name for hint text.

font_name_hint_text is an StringProperty and defaults to ‘Roboto’.

font_name_max_length

Font name for max text length.

font_name_max_length is an StringProperty and defaults to ‘Roboto’.

cancel_all_animations_on_double_click(self)

Cancels the animations of the text field when double-clicking on the text field.

set_colors_to_updated(self, interval: float | int)

set_default_colors(self, interval: float | int, updated: bool = False)

Sets the default text field colors when initializing a text field object. Also called when the application palette changes.

Parameters:

updated – If True - the color theme of the application has been changed. Updating the meanings of the colors.

set_notch_rectangle(self, joining: bool = False)

Animates a notch for the hint text in the rectangle of the text field of type rectangle.

set_active_underline_width(self, width: float | int)

Animates the width of the active underline line.

set_static_underline_color(self, color: list)

Animates the color of a static underline line.

set_active_underline_color(self, color: list)

Animates the fill color for ‘fill’ mode.

set_fill_color(self, color: list)

Animates the color of the hint text.

set_helper_text_color(self, color: list)

Animates the color of the hint text.

set_max_length_text_color(self, color: list)

Animates the color of the max length text.

set_icon_right_color(self, color: list)

Animates the color of the icon right.

set_icon_left_color(self, color: list)

Animates the color of the icon left.

set_hint_text_color(self, focus: bool, error: bool = False)

Animates the color of the hint text.

set_pos_hint_text(self, y: float, x: float = 12)

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

set_hint_text_font_size(self, font_size: float)

Animates the font size of the hint text.

set_max_text_length(self)

Called when text is entered into a text field.

check_text(self, interval: float | int)

set_text(self, instance_text_field, text: str)

Called when text is entered into a text field.

set_x_pos(self)

set_objects_labels(self)

Creates labels objects for the parameters`helper_text`,`hint_text`, etc.

on_helper_text(self, instance_text_field, helper_text: str)

on_focus(self, instance_text_field, focus: bool)

on_icon_left(self, instance_text_field, icon_name: str)

on_icon_right(self, instance_text_field, icon_name: str)

on_disabled(self, instance_text_field, disabled_value: bool)

on_error(self, instance_text_field, error: bool)

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

on_hint_text(self, instance_text_field, hint_text: str)

on_width(self, instance_text_field, width: float)

Called when the application window is resized.

on_height(self, instance_text_field, value_height: float)

on_text_color_normal(self, instance_text_field, color: list | str)

on_hint_text_color_normal(self, instance_text_field, color: list | str)

on_helper_text_color_normal(self, instance_text_field, color: list | str)

on_icon_right_color_normal(self, instance_text_field, color: list | str)

on_line_color_normal(self, instance_text_field, color: list | str)

on_max_length_text_color(self, instance_text_field, color: list | str)