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
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()
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
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
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.
- line_anim¶
If True, then text field shows animated line when on focus.
line_anim
is anBooleanProperty
and defaults to True.
- get_rect_instruction(self)¶
- get_color_instruction(self)¶
- 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 anColorProperty
and defaults to None.
- line_color_focus¶
Line color focus in
rgba
format.line_color_focus
is anColorProperty
and defaults to None.
- line_anim¶
If True, then text field shows animated line when on focus.
line_anim
is anBooleanProperty
and defaults to True.
- error_color¶
Error color in
rgba
format forrequired = True
.error_color
is anColorProperty
and defaults to None.
- fill_color¶
The background color of the fill in rgba format when the
mode
parameter is “fill”.fill_color
is anColorProperty
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 anColorProperty
and defaults to None.
- 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 anColorProperty
and defaults to (0, 0, 0, 1).
- text_color¶
Text color in
rgba
format.text_color
is anColorProperty
and defaults to None.
- font_size¶
Font size of the text in pixels.
font_size
is aNumericProperty
and defaults to ’16sp’.
- max_height¶
Maximum height of the text box when multiline = True.
max_height
is aNumericProperty
and defaults to 0.
- radius¶
The corner radius for a text field in fill mode.
radius
is aListProperty
and defaults to [10, 10, 0, 0].
- font_name_helper_text¶
Font name for helper text.
font_name_helper_text
is anStringProperty
and defaults to ‘Roboto’.
- font_name_hint_text¶
Font name for hint text.
font_name_hint_text
is anStringProperty
and defaults to ‘Roboto’.
- font_name_max_length¶
Font name for max text length.
font_name_max_length
is anStringProperty
and defaults to ‘Roboto’.
- check_text(self, interval)¶
- set_objects_labels(self)¶
Creates labels objects for the parameters helper_text,`hint_text`, etc.
- on_font_name_helper_text(self, instance, value)¶
- on_font_name_hint_text(self, instance, value)¶
- on_font_name_max_length(self, instance, value)¶
- 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)¶
- set_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 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 anColorProperty
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 anColorProperty
and defaults to (0, 0, 0, 1).
- line_color¶
Field line color.
line_color
is anColorProperty
and defaults to None.
- normal_color¶
Field color if focus is False.
normal_color
is anColorProperty
and defaults to None.
- color_active¶
Field color if focus is True.
color_active
is anColorProperty
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)¶