Text fields#
#
See also
Text fields let users enter text into a UI.
Make sure text fields look interactive
Two types: filled and outlined
The text field’s state (blank, with input, error, etc) should be visible at a glance
Keep labels and error messages brief and easy to act on
Text fields commonly appear in forms and dialogs
Filled text field
Outlined text field
Usage#
MDTextField:
mode: "filled"
MDTextFieldLeadingIcon:
icon: "magnify"
MDTextFieldHintText:
text: "Hint text"
MDTextFieldHelperText:
text: "Helper text"
mode: "persistent"
MDTextFieldTrailingIcon:
icon: "information"
MDTextFieldMaxLengthText:
max_text_length: 10
Anatomy#
Available types of text fields#
Filled mode#
MDTextField:
mode: "filled"
Outlined mode#
MDTextField:
mode: "outlined"
Example#
from kivy.lang import Builder
from kivymd.app import MDApp
KV = '''
MDScreen:
md_bg_color: app.theme_cls.backgroundColor
MDTextField:
mode: "outlined"
size_hint_x: None
width: "240dp"
pos_hint: {"center_x": .5, "center_y": .5}
MDTextFieldLeadingIcon:
icon: "account"
MDTextFieldHintText:
text: "Outlined"
MDTextFieldHelperText:
text: "Helper text"
mode: "persistent"
MDTextFieldTrailingIcon:
icon: "information"
MDTextFieldMaxLengthText:
max_text_length: 10
'''
class Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Olive"
return Builder.load_string(KV)
Example().run()
from kivymd.uix.textfield import (
MDTextField,
MDTextFieldLeadingIcon,
MDTextFieldHintText,
MDTextFieldHelperText,
MDTextFieldTrailingIcon,
MDTextFieldMaxLengthText,
)
from kivymd.uix.screen import MDScreen
from kivymd.app import MDApp
class Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Olive"
return MDScreen(
MDTextField(
MDTextFieldLeadingIcon(
icon="account",
),
MDTextFieldHintText(
text="Hint text",
),
MDTextFieldHelperText(
text="Helper text",
mode="persistent",
),
MDTextFieldTrailingIcon(
icon="information",
),
MDTextFieldMaxLengthText(
max_text_length=10,
),
mode="outlined",
size_hint_x=None,
width="240dp",
pos_hint={"center_x": 0.5, "center_y": 0.5},
),
md_bg_color=self.theme_cls.backgroundColor,
)
Example().run()
API break#
1.2.0 version#
MDTextField:
mode: "rectangle"
hint_text: "Hint text"
helper_text: "Helper text"
helper_text_mode: "persistent"
max_text_length: 10
icon_right: "information"
2.0.0 version#
Note
The text field with the round type was removed in version 2.0.0.
MDTextField:
mode: "outlined"
MDTextFieldLeadingIcon:
icon: "phone"
MDTextFieldTrailingIcon:
icon: "information"
MDTextFieldHintText:
text: "Hint text"
MDTextFieldHelperText:
text: "Helper text"
mode: "persistent"
MDTextFieldMaxLengthText:
max_text_length: 10
API - kivymd.uix.textfield.textfield
#
- class kivymd.uix.textfield.textfield.AutoFormatTelephoneNumber#
Implements automatic formatting of the text entered in the text field according to the mask, for example ‘+38 (###) ### ## ##’.
Warning
This class has not yet been implemented and it is not recommended to use it yet.
- class kivymd.uix.textfield.textfield.Validator#
Container class for various validation methods.
- datetime_date#
The last valid date as a <class ‘datetime.date’> object.
datetime_date
is anObjectProperty
and defaults to None.
- date_interval#
The date interval that is valid for input. Can be entered as <class ‘datetime.date’> objects or a string format. Both values or just one value can be entered.
In string format, must follow the current date_format. Example: Given date_format -> “mm/dd/yyyy” Input examples -> “12/31/1900”, “12/31/2100” or “12/31/1900”, None.
date_interval
is anListProperty
and defaults to [None, None].
- date_format#
Format of date strings that will be entered. Available options are: ‘dd/mm/yyyy’, ‘mm/dd/yyyy’, ‘yyyy/mm/dd’.
date_format
is anOptionProperty
and defaults to None.
- class kivymd.uix.textfield.textfield.BaseTextFieldLabel(*args, **kwargs)#
Base texture for
MDTextField
class (helper text, max length, hint text).For more information, see in the
MDLabel
class documentation.New in version 2.0.0.
- 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.
Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_color_normal to text_color_normal.
MDTextField: mode: "filled" MDTextFieldHintText: text: "Hint text color normal" text_color_normal: "brown"
text_color_normal
is anColorProperty
and defaults to None.
- text_color_focus#
Text color in (r, g, b, a) or string format when the text field has focus.
New in version 1.0.0.
Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_color_focus to text_color_focus.
MDTextField: MDTextFieldHelperText: text: "Helper text color focus" text_color_focus: "brown"
text_color_focus
is anColorProperty
and defaults to None.
- class kivymd.uix.textfield.textfield.MDTextFieldHelperText(*args, **kwargs)#
Implements the helper text label.
For more information, see in the
BaseTextFieldLabel
class documentation.New in version 2.0.0.
- mode#
Helper text mode. Available options are: ‘on_error’, ‘persistent’, ‘on_focus’.
Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from helper_text_mode to mode.
On focus#
MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "on_focus"
On error#
MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "on_error" MDTextFieldMaxLengthText: max_text_length: 5
Persistent#
MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "persistent"
mode
is anOptionProperty
and defaults to ‘on_focus’.
- class kivymd.uix.textfield.textfield.MDTextFieldMaxLengthText(*args, **kwargs)#
Implements the max length text label.
For more information, see in the
BaseTextFieldLabel
class documentation.New in version 2.0.0.
- max_text_length#
Maximum allowed value of characters in a text field.
Changed in version 2.0.0: The property was moved from class:~MDTextField.
MDTextField: mode: "filled" MDTextFieldMaxLengthText: max_text_length: 10
max_text_length
is anNumericProperty
and defaults to None.
- class kivymd.uix.textfield.textfield.MDTextFieldHintText(*args, **kwargs)#
Implements the hint text label.
For more information, see in the
BaseTextFieldLabel
class documentation.New in version 2.0.0.
MDTextField: mode: "filled" MDTextFieldHintText: text: "Hint text"
- class kivymd.uix.textfield.textfield.BaseTextFieldIcon(*args, **kwargs)#
Base texture for
MDTextField
class (helper text, max length, hint text).For more information, see in the
MDIcon
class documentation.Changed in version 2.0.0.
- icon_color_normal#
Icon color in (r, g, b, a) or string format when text field is out of focus.
New in version 1.0.0.
Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from icon_right_color_normal/icon_left_color_normal to icon_color_normal.
MDTextField: mode: "filled" MDTextFieldLeadingIcon: icon: "phone" theme_icon_color: "Custom" icon_color_normal: "lightgreen" MDTextFieldHintText: text: "Leading icon color normal"
icon_color_normal
is anColorProperty
and defaults to None.
- icon_color_focus#
Icon color in (r, g, b, a) or string format when the text field has focus.
New in version 1.0.0.
Changed in version 2.0.0: The property was moved from class:~MDTextField class and renamed from icon_right_color_focus/icon_left_color_focus ` to `icon_color_focus.
MDTextField: mode: "filled" MDTextFieldLeadingIcon: icon: "phone" theme_icon_color: "Custom" icon_color_focus: "lightgreen" MDTextFieldHintText: text: "Leading icon color focus"
icon_color_focus
is anColorProperty
and defaults to None.
- class kivymd.uix.textfield.textfield.MDTextFieldLeadingIcon(*args, **kwargs)#
Implements the leading icon.
For more information, see in the
BaseTextFieldIcon
class documentation.New in version 2.0.0.
MDTextField: mode: "filled" MDTextFieldLeadingIcon: icon: "phone" MDTextFieldHintText: text: "Field with leading icon"
- class kivymd.uix.textfield.textfield.MDTextFieldTrailingIcon(*args, **kwargs)#
Implements the trailing icon.
For more information, see in the
BaseTextFieldIcon
class documentation.New in version 2.0.0.
MDTextField: mode: "filled" MDTextFieldTrailingIcon: icon: "phone" MDTextFieldHintText: text: "Field with trailing icon"
- class kivymd.uix.textfield.textfield.MDTextField(*args, **kwargs)#
Textfield class.
For more information, see in the
DeclarativeBehavior
andBackgroundColorBehavior
andThemableBehavior
andTextInput
andValidator
andAutoFormatTelephoneNumber
andStateLayerBehavior
classes documentation.- font_style#
Name of the style for the input text.
New in version 2.0.0.
See also
font_style
is anStringProperty
and defaults to ‘Body’.
- role#
Role of font style.
New in version 2.0.0.
See also
role
is anStringProperty
and defaults to ‘large’.
- mode#
Text field mode. Available options are: ‘outlined’, ‘filled’.
mode
is anOptionProperty
and defaults to ‘outlined’.
- error_color#
Error color in (r, g, b, a) or string format for required = True or when the text field is in error state.
error_color
is anColorProperty
and defaults to None.
- error#
If True, then the text field goes into error mode.
error
is anBooleanProperty
and defaults to False.
- 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: theme_text_color: "Custom" text_color_normal: "green" text: "Text color normal"
text_color_normal
is anColorProperty
and defaults to None.
- 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: theme_text_color: "Custom" text_color_focus: "green" text: "Text color focus"
text_color_focus
is anColorProperty
and defaults to None.
- radius#
The corner radius for a text field in filled/outlined mode.
radius
is aVariableListProperty
and defaults to [dp(4), dp(4), 0, 0].
- required#
Required text. If True then the text field requires text.
required
is anBooleanProperty
and defaults to False.
- line_color_normal#
Line color normal (active indicator) in (r, g, b, a) or string format.
MDTextField: mode: "filled" theme_line_color: "Custom" line_color_normal: "green" MDTextFieldHelperText: text: "Line color normal" mode: "persistent"
line_color_normal
is anColorProperty
and defaults to None.
- line_color_focus#
Line color focus (active indicator) in (r, g, b, a) or string format.
MDTextField: mode: "filled" theme_line_color: "Custom" line_color_focus: "green" MDTextFieldHelperText: text: "Line color focus" mode: "persistent"
line_color_focus
is anColorProperty
and defaults to None.
- fill_color_normal#
Fill background color in (r, g, b, a) or string format in ‘fill’ mode when] text field is out of focus.
MDTextField: mode: "filled" theme_bg_color: "Custom" fill_color_normal: 0, 1, 0, .2 MDTextFieldHelperText: text: "Fill color normal" mode: "persistent"
fill_color_normal
is anColorProperty
and defaults to None.
- fill_color_focus#
Fill background color in (r, g, b, a) or string format in ‘fill’ mode when the text field has focus.
MDTextField: mode: "filled" theme_bg_color: "Custom" fill_color_focus: 0, 1, 0, .2 MDTextFieldHelperText: text: "Fill color focus" mode: "persistent"
fill_color_focus
is anColorProperty
and defaults to None.
- max_height#
Maximum height of the text box when multiline = True.
MDTextField: mode: "filled" max_height: "200dp" multiline: True MDTextFieldHelperText: text: "multiline=True" mode: "persistent"
max_height
is aNumericProperty
and defaults to 0.
- phone_mask#
This property has not yet been implemented and it is not recommended to use it yet.
phone_mask
is aStringProperty
and defaults to ‘’.
- 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: mode: "filled" validator: "email" MDTextFieldHintText: text: "Email" MDTextFieldHelperText: text: "user@gmail.com" mode: "persistent"
from kivy.lang import Builder from kivymd.app import MDApp KV = ''' MDScreen: md_bg_color: self.theme_cls.backgroundColor MDBoxLayout: orientation: "vertical" spacing: "20dp" adaptive_height: True size_hint_x: .8 pos_hint: {"center_x": .5, "center_y": .5} MDTextField: validator: "date" date_format: "dd/mm/yyyy" MDTextFieldHintText: text: "Date dd/mm/yyyy without limits" MDTextFieldHelperText: text: "Enter a valid dd/mm/yyyy date" MDTextField: validator: "date" date_format: "mm/dd/yyyy" MDTextFieldHintText: text: "Date mm/dd/yyyy without limits" MDTextFieldHelperText: text: "Enter a valid mm/dd/yyyy date" MDTextField: validator: "date" date_format: "yyyy/mm/dd" MDTextFieldHintText: text: "Date yyyy/mm/dd without limits" MDTextFieldHelperText: text: "Enter a valid yyyy/mm/dd date" MDTextField: validator: "date" date_format: "dd/mm/yyyy" date_interval: "01/01/1900", "01/01/2100" MDTextFieldHintText: text: "Date dd/mm/yyyy in [01/01/1900, 01/01/2100] interval" MDTextFieldHelperText: text: "Enter a valid dd/mm/yyyy date" MDTextField: validator: "date" date_format: "dd/mm/yyyy" date_interval: "01/01/1900", None MDTextFieldHintText: text: "Date dd/mm/yyyy in [01/01/1900, None] interval" MDTextFieldHelperText: text: "Enter a valid dd/mm/yyyy date" MDTextField: validator: "date" date_format: "dd/mm/yyyy" date_interval: None, "01/01/2100" MDTextFieldHintText: text: "Date dd/mm/yyyy in [None, 01/01/2100] interval" MDTextFieldHelperText: text: "Enter a valid dd/mm/yyyy date" ''' class Example(MDApp): def build(self): self.theme_cls.primary_palette = "Olive" return Builder.load_string(KV) Example().run()
validator
is anOptionProperty
and defaults to None.
- update_colors(theme_manager: kivymd.theming.ThemeManager, theme_color: str) None #
Fired when the primary_palette or theme_style value changes.
- add_widget(widget, index=0, canvas=None)#
Add a new widget as a child of this widget.
- Parameters:
- widget:
Widget
Widget to add to our list of children.
- index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.
New in version 1.0.5.
- canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.
New in version 1.9.0.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- set_texture_color(texture, canvas_group, color: list, error: bool = False) None #
Animates the color of the leading/trailing icons/hint/helper/max length text.
- set_pos_hint_text(y: float, x: float) None #
Animates the x-axis width and y-axis height of the hint text.
- set_space_in_line(left_width: float | int, right_width: float | int) None #
Animates the length of the right line of the text field for the hint text.
- set_max_text_length() None #
Fired when text is entered into a text field. Set max length text and updated max length texture.