Text Field

See also

Material Design spec, Text fields

Text fields let users enter and edit text.

KivyMD provides the following field classes for use:

• MDTextField

• MDTextFieldRound

• 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 = '''
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()

Helper text mode ‘on_error’ (with required)

MDTextField:
    hint_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"

Color mode

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

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

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

MDTextField:
    hint_text: "Line color normal"
    line_color_normal: app.theme_cls.accent_color

Rectangle mode

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

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"

Warning

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

MDTextFieldRound

Without icon

MDTextFieldRound:
    hint_text: 'Empty field'

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"

With left and right icons

MDTextFieldRound:
    icon_left: 'key-variant'
    icon_right: 'eye-off'
    hint_text: 'Field with left and right icons'

Control background color

MDTextFieldRound:
    icon_left: 'key-variant'
    normal_color: app.theme_cls.accent_color

MDTextFieldRound:
    icon_left: 'key-variant'
    normal_color: app.theme_cls.accent_color
    color_active: 1, 0, 0, 1

See also

See more information in the MDTextFieldRect class.

API - kivymd.uix.textfield

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

Bases: kivymd.theming.ThemableBehavior, kivy.uix.textinput.TextInput

anim_rect(self, points, alpha)

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

Bases: kivymd.theming.ThemableBehavior, kivymd.uix.textfield.FixedHintTextInput

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

mode is an OptionProperty and defaults to ‘line’.

line_color_normal

Line color normal in rgba format.

line_color_normal is an ListProperty and defaults to [].

line_color_focus

Line color focus in rgba format.

line_color_focus is an ListProperty and defaults to [].

error_color

Error color in rgba format for required = True.

error_color is an ListProperty and defaults to [].

error

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

error is an BooleanProperty and defaults to False.

on_width(self, instance, width)

on_focus(self, *args)

on_text(self, instance, text)

on_text_validate(self)

on_color_mode(self, instance, mode)

on_line_color_focus(self, *args)

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

Bases: kivymd.theming.ThemableBehavior, kivy.uix.textinput.TextInput

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 ListProperty 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 ListProperty and defaults to [0, 0, 0, 1].

line_color

Field line color.

line_color is an ListProperty and defaults to [].

normal_color

Field color if focus is False.

normal_color is an ListProperty and defaults to [].

color_active

Field color if focus is True.

color_active is an ListProperty and defaults to [].

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)