Text Field¶
See also
Text fields let users enter and edit text.
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"
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"
Fill mode¶
MDTextField:
hint_text: "Fill mode"
mode: "fill"
fill_color: 0, 0, 0, .4
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
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
MDTextField:
hint_text: "Name"
icon_right: "arrow-down-drop-circle-outline"
icon_right_color: app.theme_cls.primary_color
MDTextField:
hint_text: "Name"
mode: "rectangle"
icon_right: "arrow-down-drop-circle-outline"
icon_right_color: app.theme_cls.primary_color
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 thetext
, the updates occur on the next clock cycle and not instantly. This might cause any changes to theTextInput
that occur between the modification and the next cycle to be ignored, or to use previous values. For example, after a update to thetext
, 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 usingschedule_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 fromFocusBehavior
.keyboard_mode
,show_keyboard()
,hide_keyboard()
,focus()
, andinput_type
have been removed since they are now inherited fromFocusBehavior
.Changed in version 1.7.0: on_double_tap, on_triple_tap and on_quad_touch events added.
-
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 thetext
, the updates occur on the next clock cycle and not instantly. This might cause any changes to theTextInput
that occur between the modification and the next cycle to be ignored, or to use previous values. For example, after a update to thetext
, 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 usingschedule_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 fromFocusBehavior
.keyboard_mode
,show_keyboard()
,hide_keyboard()
,focus()
, andinput_type
have been removed since they are now inherited fromFocusBehavior
.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 anStringProperty
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 anOptionProperty
and defaults to ‘none’.
-
max_text_length
¶ Maximum allowed value of characters in a text field.
max_text_length
is anNumericProperty
and defaults to None.
-
required
¶ Required text. If True then the text field requires text.
required
is anBooleanProperty
and defaults to False.
-
color_mode
¶ Color text mode. Available options are: ‘primary’, ‘accent’, ‘custom’.
color_mode
is anOptionProperty
and defaults to ‘primary’.
-
mode
¶ Text field mode. Available options are: ‘line’, ‘rectangle’, ‘fill’.
mode
is anOptionProperty
and defaults to ‘line’.
-
line_color_normal
¶ Line color normal in
rgba
format.line_color_normal
is anListProperty
and defaults to [].
-
line_color_focus
¶ Line color focus in
rgba
format.line_color_focus
is anListProperty
and defaults to [].
-
error_color
¶ Error color in
rgba
format forrequired = True
.error_color
is anListProperty
and defaults to [].
-
fill_color
¶ The background color of the fill in rgba format when the
mode
parameter is “fill”.fill_color
is anListProperty
and defaults to [0, 0, 0, 0].
-
active_line
¶ Show active line or not.
active_line
is anBooleanProperty
and defaults to True.
-
error
¶ If True, then the text field goes into
error
mode.error
is anBooleanProperty
and defaults to False.
-
current_hint_text_color
¶ hint_text
text color.current_hint_text_color
is anListProperty
and defaults to [].
-
icon_right
¶ Right icon.
icon_right
is anStringProperty
and defaults to ‘’.
-
icon_right_color
¶ Color of right icon in
rgba
format.icon_right_color
is anListProperty
and defaults to [0, 0, 0, 1].
-
on_icon_right
(self, instance, value)¶
-
on_icon_right_color
(self, instance, value)¶
-
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)¶ 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 thetext
, the updates occur on the next clock cycle and not instantly. This might cause any changes to theTextInput
that occur between the modification and the next cycle to be ignored, or to use previous values. For example, after a update to thetext
, 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 usingschedule_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 fromFocusBehavior
.keyboard_mode
,show_keyboard()
,hide_keyboard()
,focus()
, andinput_type
have been removed since they are now inherited fromFocusBehavior
.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 anStringProperty
and defaults to ‘’.
-
icon_left_color
¶ Color of left icon in
rgba
format.icon_left_color
is anListProperty
and defaults to [0, 0, 0, 1].
-
icon_right
¶ Right icon.
icon_right
is anStringProperty
and defaults to ‘’.
-
icon_right_color
¶ Color of right icon.
icon_right_color
is anListProperty
and defaults to [0, 0, 0, 1].
-
line_color
¶ Field line color.
line_color
is anListProperty
and defaults to [].
-
normal_color
¶ Field color if focus is False.
normal_color
is anListProperty
and defaults to [].
-
color_active
¶ Field color if focus is True.
color_active
is anListProperty
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)¶