Text Field

Text fields let users enter and edit text.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields.png

KivyMD provides the following field classes for use:

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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-no-helper-mode.gif

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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-helper-mode-on-focus.gif

Persistent helper text mode

MDTextField:
    hint_text: "Persistent helper text"
    helper_text: "Text is always here"
    helper_text_mode: "persistent"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-helper-mode-persistent.gif

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 = '''
BoxLayout:
    padding: "10dp"

    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_y": .5}
'''


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

    def build(self):
        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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-helper-mode-on-error.gif

Helper text mode ‘on_error’ (with required)

MDTextField:
    hint_text: "required = True"
    required: True
    helper_text_mode: "on_error"
    helper_text: "Enter text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-required.gif

Text length control

MDTextField:
    hint_text: "Max text length = 5"
    max_text_length: 5
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-text-length.gif

Multi line text

MDTextField:
    multiline: True
    hint_text: "Multi-line text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-text-multi-line.gif

Color mode

MDTextField:
    hint_text: "color_mode = 'accent'"
    color_mode: 'accent'

Available options are ‘primary’, ‘accent’ or ‘custom’.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-color-mode.gif
MDTextField:
    hint_text: "color_mode = 'custom'"
    color_mode: 'custom'
    helper_text_mode: "on_focus"
    helper_text: "Color is defined by 'line_color_focus' property"
    line_color_focus: 1, 0, 1, 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-color-mode-custom.gif
MDTextField:
    hint_text: "Line color normal"
    line_color_normal: app.theme_cls.accent_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-line-color-normal.png

Rectangle mode

MDTextField:
    hint_text: "Rectangle mode"
    mode: "rectangle"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-rectangle-mode.gif

Fill mode

MDTextField:
    hint_text: "Fill mode"
    mode: "fill"
    fill_color: 0, 0, 0, .4
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-fill-mode.gif

Maximum height

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen

    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}
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-fill-mode-multiline-max-height.gif

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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-rect.gif

Warning

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

MDTextFieldRound

Without icon

MDTextFieldRound:
    hint_text: 'Empty field'
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-round.gif

With left icon

Warning

The icons in the MDTextFieldRound are static. You cannot bind events to them.

MDTextFieldRound:
    icon_left: "email"
    hint_text: "Field with left icon"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-round-left-icon.png

With left and right icons

MDTextFieldRound:
    icon_left: 'key-variant'
    icon_right: 'eye-off'
    hint_text: 'Field with left and right icons'
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-round-left-right-icon.png

Control background color

MDTextFieldRound:
    icon_left: 'key-variant'
    normal_color: app.theme_cls.accent_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-round-normal-color.gif
MDTextFieldRound:
    icon_left: 'key-variant'
    normal_color: app.theme_cls.accent_color
    color_active: 1, 0, 0, 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-round-active-color.gif

Clickable icon for MDTextFieldRound

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

    MDTextFieldRound:
        id: text_field
        hint_text: root.hint_text
        text: root.text
        password: True
        color_active: app.theme_cls.primary_light
        icon_left: "key-variant"
        padding:
            self._lbl_icon_left.texture_size[1] + dp(10) if self.icon_left else dp(15),                 (self.height / 2) - (self.line_height / 2),                 self._lbl_icon_right.texture_size[1] + dp(20),                 0

    MDIconButton:
        icon: "eye-off"
        ripple_scale: .5
        pos_hint: {"center_y": .5}
        pos: text_field.width - self.width + dp(8), 0
        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()

With right icon

Note

The icon on the right is available for use in all text fields.

MDTextField:
    hint_text: "Name"
    mode: "fill"
    fill_color: 0, 0, 0, .4
    icon_right: "arrow-down-drop-circle-outline"
    icon_right_color: app.theme_cls.primary_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-fill-mode-icon.png
MDTextField:
    hint_text: "Name"
    icon_right: "arrow-down-drop-circle-outline"
    icon_right_color: app.theme_cls.primary_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-right-icon.png
MDTextField:
    hint_text: "Name"
    mode: "rectangle"
    icon_right: "arrow-down-drop-circle-outline"
    icon_right_color: app.theme_cls.primary_color
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-rectangle-right-icon.png

See also

See more information in the MDTextFieldRect class.

API - kivymd.uix.textfield

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

TextInput class. See module documentation for more information.

Events
on_text_validate

Fired only in multiline=False mode when the user hits ‘enter’. This will also unfocus the textinput.

on_double_tap

Fired when a double tap happens in the text input. The default behavior selects the text around the cursor position. More info at on_double_tap().

on_triple_tap

Fired when a triple tap happens in the text input. The default behavior selects the line around the cursor position. More info at on_triple_tap().

on_quad_touch

Fired when four fingers are touching the text input. The default behavior selects the whole text. More info at on_quad_touch().

Warning

When changing a TextInput property that requires re-drawing, e.g. modifying the text, the updates occur on the next clock cycle and not instantly. This might cause any changes to the TextInput that occur between the modification and the next cycle to be ignored, or to use previous values. For example, after a update to the text, changing the cursor in the same clock frame will move it using the previous text and will likely end up in an incorrect position. The solution is to schedule any updates to occur on the next clock cycle using schedule_once().

Note

Selection is cancelled when TextInput is focused. If you need to show selection when TextInput is focused, you should delay (use Clock.schedule) the call to the functions for selecting text (select_all, select_text).

Changed in version 1.10.0: background_disabled_active has been removed.

Changed in version 1.9.0: TextInput now inherits from FocusBehavior. keyboard_mode, show_keyboard(), hide_keyboard(), focus(), and input_type have been removed since they are now inherited from FocusBehavior.

Changed in version 1.7.0: on_double_tap, on_triple_tap and on_quad_touch events added.

line_anim

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

line_anim is an BooleanProperty and defaults to True.

anim_rect(self, points, alpha)
class kivymd.uix.textfield.MDTextField(**kwargs)

TextInput class. See module documentation for more information.

Events
on_text_validate

Fired only in multiline=False mode when the user hits ‘enter’. This will also unfocus the textinput.

on_double_tap

Fired when a double tap happens in the text input. The default behavior selects the text around the cursor position. More info at on_double_tap().

on_triple_tap

Fired when a triple tap happens in the text input. The default behavior selects the line around the cursor position. More info at on_triple_tap().

on_quad_touch

Fired when four fingers are touching the text input. The default behavior selects the whole text. More info at on_quad_touch().

Warning

When changing a TextInput property that requires re-drawing, e.g. modifying the text, the updates occur on the next clock cycle and not instantly. This might cause any changes to the TextInput that occur between the modification and the next cycle to be ignored, or to use previous values. For example, after a update to the text, changing the cursor in the same clock frame will move it using the previous text and will likely end up in an incorrect position. The solution is to schedule any updates to occur on the next clock cycle using schedule_once().

Note

Selection is cancelled when TextInput is focused. If you need to show selection when TextInput is focused, you should delay (use Clock.schedule) the call to the functions for selecting text (select_all, select_text).

Changed in version 1.10.0: background_disabled_active has been removed.

Changed in version 1.9.0: TextInput now inherits from FocusBehavior. keyboard_mode, show_keyboard(), hide_keyboard(), focus(), and input_type have been removed since they are now inherited from FocusBehavior.

Changed in version 1.7.0: on_double_tap, on_triple_tap and on_quad_touch events added.

helper_text

Text for helper_text mode.

helper_text is an StringProperty and defaults to ‘This field is required’.

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.

color_mode

Color text mode. Available options are: ‘primary’, ‘accent’, ‘custom’.

color_mode is an OptionProperty and defaults to ‘primary’.

mode

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

mode is an OptionProperty and defaults to ‘line’.

line_color_normal

Line color normal in rgba format.

line_color_normal is an ColorProperty and defaults to None.

line_color_focus

Line color focus in rgba format.

line_color_focus is an ColorProperty and defaults to None.

line_anim

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

line_anim is an BooleanProperty and defaults to True.

error_color

Error color in rgba format for required = True.

error_color is an ColorProperty and defaults to None.

fill_color

The background color of the fill in rgba format when the mode parameter is “fill”.

fill_color 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.

current_hint_text_color

hint_text text color.

current_hint_text_color is an ColorProperty and defaults to None.

icon_right

Right icon.

icon_right is an StringProperty and defaults to ‘’.

icon_right_color

Color of right icon in rgba format.

icon_right_color is an ColorProperty and defaults to (0, 0, 0, 1).

text_color

Text color in rgba format.

text_color is an ColorProperty and defaults to None.

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.

max_height is a NumericProperty and defaults to 0.

set_objects_labels(self)

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

on_icon_right(self, instance, value)
on_icon_right_color(self, instance, value)
on_width(self, instance, width)

Called when the application window is resized.

on_focus(self, *args)
on_disabled(self, *args)
on_text(self, instance, text)
on_text_validate(self)
on_color_mode(self, instance, mode)
on_line_color_focus(self, *args)
on__hint_text(self, instance, value)
on_hint_text(self, instance, value)
on_height(self, instance, value)
class kivymd.uix.textfield.MDTextFieldRound(**kwargs)

TextInput class. See module documentation for more information.

Events
on_text_validate

Fired only in multiline=False mode when the user hits ‘enter’. This will also unfocus the textinput.

on_double_tap

Fired when a double tap happens in the text input. The default behavior selects the text around the cursor position. More info at on_double_tap().

on_triple_tap

Fired when a triple tap happens in the text input. The default behavior selects the line around the cursor position. More info at on_triple_tap().

on_quad_touch

Fired when four fingers are touching the text input. The default behavior selects the whole text. More info at on_quad_touch().

Warning

When changing a TextInput property that requires re-drawing, e.g. modifying the text, the updates occur on the next clock cycle and not instantly. This might cause any changes to the TextInput that occur between the modification and the next cycle to be ignored, or to use previous values. For example, after a update to the text, changing the cursor in the same clock frame will move it using the previous text and will likely end up in an incorrect position. The solution is to schedule any updates to occur on the next clock cycle using schedule_once().

Note

Selection is cancelled when TextInput is focused. If you need to show selection when TextInput is focused, you should delay (use Clock.schedule) the call to the functions for selecting text (select_all, select_text).

Changed in version 1.10.0: background_disabled_active has been removed.

Changed in version 1.9.0: TextInput now inherits from FocusBehavior. keyboard_mode, show_keyboard(), hide_keyboard(), focus(), and input_type have been removed since they are now inherited from FocusBehavior.

Changed in version 1.7.0: on_double_tap, on_triple_tap and on_quad_touch events added.

icon_left

Left icon.

icon_left is an StringProperty and defaults to ‘’.

icon_left_color

Color of left icon in rgba format.

icon_left_color is an ColorProperty and defaults to (0, 0, 0, 1).

icon_right

Right icon.

icon_right is an StringProperty and defaults to ‘’.

icon_right_color

Color of right icon.

icon_right_color is an ColorProperty and defaults to (0, 0, 0, 1).

line_color

Field line color.

line_color is an ColorProperty and defaults to None.

normal_color

Field color if focus is False.

normal_color is an ColorProperty and defaults to None.

color_active

Field color if focus is True.

color_active is an ColorProperty and defaults to None.

on_focus(self, instance, value)
on_icon_left(self, instance, value)
on_icon_left_color(self, instance, value)
on_icon_right(self, instance, value)
on_icon_right_color(self, instance, value)
on_color_active(self, instance, value)