:github_url: https://github.com/kivymd/KivyMD/blob/master/kivymd/uix/textfield/textfield.py Text fields =========== .. py:module:: kivymd.uix.textfield.textfield .. autoapi-nested-parse:: Components/Text fields ====================== .. seealso:: `Material Design spec, Text fields `_ .. rubric:: Text fields let users enter text into a UI. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields.png :align: center - 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 .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/available-fields.png :align: center 1. Filled text field 2. Outlined text field Usage ----- .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldLeadingIcon: icon: "magnify" MDTextFieldHintText: text: "Hint text" MDTextFieldHelperText: text: "Helper text" mode: "persistent" MDTextFieldTrailingIcon: icon: "information" MDTextFieldMaxLengthText: max_text_length: 10 .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldLeadingIcon( icon="magnify", ), MDTextFieldHintText( text="Hint text", ), MDTextFieldHelperText( text="Helper text", mode="persistent", ), MDTextFieldTrailingIcon( icon="information", ), MDTextFieldMaxLengthText( max_text_length=10, ), mode="filled", ) Anatomy ------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-anatomy.png :align: center Available types of text fields ============================== Filled mode ----------- .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" .. tab:: Declarative Python style .. code-block:: python MDTextField( mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-filled-mode.png :align: center Outlined mode ------------- .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "outlined" .. tab:: Declarative Python style .. code-block:: python MDTextField( mode="outlined", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-outlined-mode.png :align: center Example ------- .. tabs:: .. tab:: Declarative KV style .. code-block:: python 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() .. tab:: Declarative Python style .. code-block:: python 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() .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-example.png :align: center API break ========= 1.2.0 version ------------- .. code-block:: kv 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`. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "outlined" MDTextFieldLeadingIcon: icon: "phone" MDTextFieldTrailingIcon: icon: "information" MDTextFieldHintText: text: "Hint text" MDTextFieldHelperText: text: "Helper text" mode: "persistent" MDTextFieldMaxLengthText: max_text_length: 10 .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldLeadingIcon( icon="magnify", ), MDTextFieldHintText( text="Hint text", ), MDTextFieldHelperText( text="Helper text", mode="persistent", ), MDTextFieldTrailingIcon( icon="information", ), MDTextFieldMaxLengthText( max_text_length=10, ), ) API - :mod:`kivymd.uix.textfield.textfield` ------------------------------------------- .. py:class:: 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. .. py:method:: isnumeric(value) -> bool .. py:method:: do_backspace(*args) -> None Do backspace operation from the current cursor position. .. py:method:: field_filter(value, boolean) -> None .. py:method:: format(value) -> None .. py:class:: Validator Container class for various validation methods. .. py:attribute:: datetime_date The last valid date as a object. :attr:`datetime_date` is an :class:`~kivy.properties.ObjectProperty` and defaults to `None`. .. py:attribute:: date_interval The date interval that is valid for input. Can be entered as 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. :attr:`date_interval` is an :class:`~kivy.properties.ListProperty` and defaults to `[None, None]`. .. py:attribute:: date_format Format of date strings that will be entered. Available options are: `'dd/mm/yyyy'`, `'mm/dd/yyyy'`, `'yyyy/mm/dd'`. :attr:`date_format` is an :class:`~kivy.properties.OptionProperty` and defaults to `None`. .. py:method:: is_email_valid(text: str) -> bool Checks the validity of the email. .. py:method:: is_time_valid(text: str) -> bool Checks the validity of the time. .. py:method:: is_date_valid(text: str) -> bool Checks the validity of the date. .. py:method:: on_date_interval(*args) -> None Default event handler for date_interval input. .. py:class:: BaseTextFieldLabel(*args, **kwargs) Base texture for :class:`~MDTextField` class (helper text, max length, hint text). For more information, see in the :class:`~kivymd.uix.label.label.MDLabel` class documentation. .. versionadded:: 2.0.0 .. py:attribute:: text_color_normal Text color in (r, g, b, a) or string format when text field is out of focus. .. versionadded:: 1.0.0 .. versionchanged:: 2.0.0 The property was moved from class:`~MDTextField` class and renamed from `helper_text_color_normal` to `text_color_normal`. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldHintText: text: "Hint text color normal" text_color_normal: "brown" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHintText( text="Hint text color normal", text_color_normal="brown", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-text-color-normal.png :align: center :attr:`text_color_normal` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: text_color_focus Text color in (r, g, b, a) or string format when the text field has focus. .. versionadded:: 1.0.0 .. versionchanged:: 2.0.0 The property was moved from class:`~MDTextField` class and renamed from `helper_text_color_focus` to `text_color_focus`. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: MDTextFieldHelperText: text: "Helper text color focus" text_color_focus: "brown" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Helper text color focus", text_color_normal="brown", ), ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-text-color-focus.png :align: center :attr:`text_color_focus` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:class:: MDTextFieldHelperText(*args, **kwargs) Implements the helper text label. For more information, see in the :class:`~BaseTextFieldLabel` class documentation. .. versionadded:: 2.0.0 .. py:attribute:: mode Helper text mode. Available options are: `'on_error'`, `'persistent'`, `'on_focus'`. .. versionchanged:: 2.0.0 The property was moved from class:`~MDTextField` class and renamed from `helper_text_mode` to `mode`. On focus -------- .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "on_focus" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Helper text", mode="on_focus", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-helper-text-mode-on-focus.gif :align: center On error -------- .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "on_error" MDTextFieldMaxLengthText: max_text_length: 5 .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Helper text", mode="on_error", ), MDTextFieldMaxLengthText( max_text_length=5, ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-helper-text-mode-on-error.gif :align: center Persistent ---------- .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldHelperText: text: "Helper text" mode: "persistent" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Helper text", mode="persistent", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-helper-text-mode-persistent.gif :align: center :attr:`mode` is an :class:`~kivy.properties.OptionProperty` and defaults to `'on_focus'`. .. py:class:: MDTextFieldMaxLengthText(*args, **kwargs) Implements the max length text label. For more information, see in the :class:`~BaseTextFieldLabel` class documentation. .. versionadded:: 2.0.0 .. py:attribute:: max_text_length Maximum allowed value of characters in a text field. .. versionchanged:: 2.0.0 The property was moved from class:`~MDTextField`. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldMaxLengthText: max_text_length: 10 .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldMaxLengthText( max_text_length=10, ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-max-text-length.png :align: center :attr:`max_text_length` is an :class:`~kivy.properties.NumericProperty` and defaults to `None`. .. py:class:: MDTextFieldHintText(*args, **kwargs) Implements the hint text label. For more information, see in the :class:`~BaseTextFieldLabel` class documentation. .. versionadded:: 2.0.0 .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldHintText: text: "Hint text" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHintText( text="Hint text", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-hint-text.gif :align: center .. py:class:: BaseTextFieldIcon(*args, **kwargs) Base texture for :class:`~MDTextField` class (helper text, max length, hint text). For more information, see in the :class:`~kivymd.uix.label.label.MDIcon` class documentation. .. versionchanged:: 2.0.0 .. py:attribute:: icon_color_normal Icon color in (r, g, b, a) or string format when text field is out of focus. .. versionadded:: 1.0.0 .. versionchanged:: 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`. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldLeadingIcon: icon: "phone" theme_icon_color: "Custom" icon_color_normal: "lightgreen" MDTextFieldHintText: text: "Leading icon color normal" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldLeadingIcon( icon="phone", theme_icon_color="Custom", icon_color_normal="lightgreen", ), MDTextFieldHintText( text="Leading icon color normal", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-leading-icon-color-normal.png :align: center :attr:`icon_color_normal` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: icon_color_focus Icon color in (r, g, b, a) or string format when the text field has focus. .. versionadded:: 1.0.0 .. versionchanged:: 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`. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldLeadingIcon: icon: "phone" theme_icon_color: "Custom" icon_color_focus: "lightgreen" MDTextFieldHintText: text: "Leading icon color focus" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldLeadingIcon( icon="phone", theme_icon_color="Custom", icon_color_focus="lightgreen", ), MDTextFieldHintText( text="Leading icon color focus", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-leading-icon-color-focus.png :align: center :attr:`icon_color_focus` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:method:: on_icon_color_normal(instance: BaseTextFieldIcon | MDTextFieldTrailingIcon, value: list | str) Called when the `icon_color_normal` property of the icon is changed. If the associated text field is set, this method triggers an update to the icon's color appearance, ensuring that the correct color is used based on the focus state of the text field. Typically used to visually reflect property changes in real time in response to user interaction or theme updates. :param instance: The instance of `BaseTextFieldIcon` that had its `icon_color_normal` property changed. :param value: The new color value, either as a list of RGBA components or a string (e.g., a hex color or color name). .. py:class:: MDTextFieldLeadingIcon(*args, **kwargs) Implements the leading icon. For more information, see in the :class:`~BaseTextFieldIcon` class documentation. .. versionadded:: 2.0.0 .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldLeadingIcon: icon: "phone" MDTextFieldHintText: text: "Field with leading icon" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldLeadingIcon( icon="phone", ), MDTextFieldHintText( text="Field with leading icon", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-leading-icon.png :align: center .. py:class:: MDTextFieldTrailingIcon(*args, **kwargs) Implements the trailing icon. For more information, see in the :class:`~BaseTextFieldIcon` class documentation. .. versionadded:: 2.0.0 .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" MDTextFieldTrailingIcon: icon: "phone" MDTextFieldHintText: text: "Field with trailing icon" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldTrailingIcon( icon="phone", ), MDTextFieldHintText( text="Field with trailing icon", ), mode="filled", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-trailing-icon.png :align: center .. py:class:: MDTextField(*args, **kwargs) Textfield class. For more information, see in the :class:`~kivymd.uix.behaviors.declarative_behavior.DeclarativeBehavior` and :class:`~kivymd.uix.behaviors.backgroundcolor_behavior.BackgroundColorBehavior` and :class:`~kivymd.theming.ThemableBehavior` and :class:`~kivy.uix.textinput.TextInput` and :class:`~Validator` and :class:`~AutoFormatTelephoneNumber` and :class:`~kivymd.uix.behaviors.state_layer_behavior.StateLayerBehavior` classes documentation. .. py:attribute:: font_style Name of the style for the input text. .. versionadded:: 2.0.0 .. seealso:: `Font style names `_ :attr:`font_style` is an :class:`~kivy.properties.StringProperty` and defaults to `'Body'`. .. py:attribute:: role Role of font style. .. versionadded:: 2.0.0 .. seealso:: `Font style roles `_ :attr:`role` is an :class:`~kivy.properties.StringProperty` and defaults to `'large'`. .. py:attribute:: mode Text field mode. Available options are: `'outlined'`, `'filled'`. :attr:`mode` is an :class:`~kivy.properties.OptionProperty` and defaults to `'outlined'`. .. py:attribute:: error_color Error color in (r, g, b, a) or string format for `required = True` or when the text field is in `error` state. :attr:`error_color` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: error If True, then the text field goes into `error` mode. :attr:`error` is an :class:`~kivy.properties.BooleanProperty` and defaults to `False`. .. py:attribute:: text_color_normal Text color in (r, g, b, a) or string format when text field is out of focus. .. versionadded:: 1.0.0 .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: theme_text_color: "Custom" text_color_normal: "green" text: "Text color normal" .. tab:: Declarative Python style .. code-block:: python MDTextField( theme_text_color="Custom", text_color_normal="green", text="Text color normal", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-text-color-normal.png :align: center :attr:`text_color_normal` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: text_color_focus Text color in (r, g, b, a) or string format when text field has focus. .. versionadded:: 1.0.0 .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: theme_text_color: "Custom" text_color_focus: "green" text: "Text color focus" .. tab:: Declarative Python style .. code-block:: python MDTextField( theme_text_color="Custom", text_color_focus="green", text="Text color focus", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-field-text-color-focus.png :align: center :attr:`text_color_focus` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: radius The corner radius for a text field in `filled/outlined` mode. :attr:`radius` is a :class:`~kivy.properties.VariableListProperty` and defaults to `[dp(4), dp(4), 0, 0]`. .. py:attribute:: required Required text. If True then the text field requires text. :attr:`required` is an :class:`~kivy.properties.BooleanProperty` and defaults to `False`. .. py:attribute:: line_color_normal Line color normal (active indicator) in (r, g, b, a) or string format. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" theme_line_color: "Custom" line_color_normal: "green" MDTextFieldHelperText: text: "Line color normal" mode: "persistent" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Line color normal", mode="persistent", ), mode="filled", theme_line_color="Custom", line_color_normal="green", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-line-color-normal.png :align: center :attr:`line_color_normal` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: line_color_focus Line color focus (active indicator) in (r, g, b, a) or string format. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" theme_line_color: "Custom" line_color_focus: "green" MDTextFieldHelperText: text: "Line color focus" mode: "persistent" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Line color focus", mode="persistent", ), mode="filled", theme_line_color="Custom", line_color_focus="green", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-line-color-focus.png :align: center :attr:`line_color_focus` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: fill_color_normal Fill background color in (r, g, b, a) or string format in 'fill' mode when] text field is out of focus. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" theme_bg_color: "Custom" fill_color_normal: 0, 1, 0, .2 MDTextFieldHelperText: text: "Fill color normal" mode: "persistent" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Fill color normal", mode="persistent", ), mode="filled", theme_bg_color="Custom", fill_color_normal=[0, 1, 0, .2], ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-fill-color-normal.png :align: center :attr:`fill_color_normal` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: fill_color_focus Fill background color in (r, g, b, a) or string format in 'fill' mode when the text field has focus. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" theme_bg_color: "Custom" fill_color_focus: 0, 1, 0, .2 MDTextFieldHelperText: text: "Fill color focus" mode: "persistent" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="Fill color focus", mode="persistent", ), mode="filled", theme_bg_color="Custom", fill_color_focus=[0, 1, 0, .2], ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-fill-color-focus.png :align: center :attr:`fill_color_focus` is an :class:`~kivy.properties.ColorProperty` and defaults to `None`. .. py:attribute:: max_height Maximum height of the text box when `multiline = True`. .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" max_height: "200dp" multiline: True MDTextFieldHelperText: text: "multiline=True" mode: "persistent" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHelperText( text="multiline=True", mode="persistent", ), mode="filled", max_height="200dp", multiline=True, ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-multiline.gif :align: center :attr:`max_height` is a :class:`~kivy.properties.NumericProperty` and defaults to `0`. .. py:attribute:: phone_mask This property has not yet been implemented and it is not recommended to use it yet. :attr:`phone_mask` is a :class:`~kivy.properties.StringProperty` and defaults to ''. .. py:attribute:: 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'`, :attr:`date_format` must be defined. .. versionadded:: 1.1.0 .. tabs:: .. tab:: Declarative KV style .. code-block:: kv MDTextField: mode: "filled" validator: "email" MDTextFieldHintText: text: "Email" MDTextFieldHelperText: text: "user@gmail.com" mode: "persistent" .. tab:: Declarative Python style .. code-block:: python MDTextField( MDTextFieldHintText( text="Email", ), MDTextFieldHelperText( text="user@gmail.com", mode="persistent", ), mode="filled", validator="email", ) .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-email-validator.png :align: center .. tabs:: .. tab:: Declarative KV style .. code-block:: python from kivy.lang import Builder from kivymd.app import MDApp KV = ''' MDScreen: md_bg_color: self.theme_cls.backgroundColor MDBoxLayout: orientation: "vertical" spacing: "28dp" 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() .. tab:: Declarative Python style .. code-block:: python from kivymd.app import MDApp from kivymd.uix.boxlayout import MDBoxLayout from kivymd.uix.screen import MDScreen from kivymd.uix.textfield import ( MDTextField, MDTextFieldHintText, MDTextFieldHelperText ) class Example(MDApp): def build(self): self.theme_cls.primary_palette = "Olive" return ( MDScreen( MDBoxLayout( MDTextField( MDTextFieldHintText( text="Date dd/mm/yyyy without limits", ), MDTextFieldHelperText( text="Enter a valid dd/mm/yyyy date", ), validator="date", date_format="dd/mm/yyyy", ), MDTextField( MDTextFieldHintText( text="Date mm/dd/yyyy without limits", ), MDTextFieldHelperText( text="Enter a valid mm/dd/yyyy date", ), validator="date", date_format="mm/dd/yyyy", ), MDTextField( MDTextFieldHintText( text="Date yyyy/mm/dd without limits", ), MDTextFieldHelperText( text="Enter a valid yyyy/mm/dd date", ), validator="date", date_format="yyyy/mm/dd", ), MDTextField( MDTextFieldHintText( text="Date dd/mm/yyyy in [01/01/1900, 01/01/2100] interval", ), MDTextFieldHelperText( text="Enter a valid dd/mm/yyyy date", ), validator="date", date_format="dd/mm/yyyy", date_interval=["01/01/1900", "01/01/2100"], ), MDTextField( MDTextFieldHintText( text="Date dd/mm/yyyy in [01/01/1900, None] interval", ), MDTextFieldHelperText( text="Enter a valid dd/mm/yyyy date", ), validator="date", date_format="dd/mm/yyyy", date_interval=["01/01/1900", None], ), MDTextField( MDTextFieldHintText( text="Date dd/mm/yyyy in [None, 01/01/2100] interval", ), MDTextFieldHelperText( text="Enter a valid dd/mm/yyyy date", ), validator="date", date_format="dd/mm/yyyy", date_interval=[None, "01/01/2100"], ), orientation="vertical", spacing="28dp", adaptive_height=True, size_hint_x=.8, pos_hint={"center_x": .5, "center_y": .5}, ), md_bg_color=self.theme_cls.backgroundColor, ) ) Example().run() .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/text-fields-validator-date.png :align: center :attr:`validator` is an :class:`~kivy.properties.OptionProperty` and defaults to `None`. .. py:method:: update_colors(theme_manager: kivymd.theming.ThemeManager, theme_color: str) -> None Fired when the `primary_palette` or `theme_style` value changes. .. py:method:: add_widget(widget, index=0, canvas=None) Add a new widget as a child of this widget. :Parameters: `widget`: :class:`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 :doc:`Widgets Programming Guide `. .. versionadded:: 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. .. versionadded:: 1.9.0 .. code-block:: python >>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider) .. py:method:: 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. .. py:method:: get_adjusted_pos_max_length_label() -> tuple Calculates the position of the max length label. Returns: tuple: (x, y) coordinates for positioning the max length label. .. py:method:: get_adjusted_pos_helper_text_label() -> tuple Calculates the position of the helper text label based on the textfield mode. Returns: tuple: (x, y) coordinates for positioning the helper text label. .. py:method:: get_adjusted_pos_trailing_icon() -> tuple Calculates the adjusted position of the trailing icon. Returns: tuple: (x, y) coordinates for positioning the trailing icon. .. py:method:: get_adjusted_pos_leading_icon() -> tuple Calculates the adjusted position of the leading icon based on the textfield mode and icon size. Returns: tuple: (x, y) coordinates for positioning the leading icon. .. py:method:: get_adjusted_pos_hint_text_label() -> tuple Calculates the adjusted position of the hint text label based on the presence of a leading icon and whether the textfield is multiline. Returns: tuple: (x, y) position coordinates for the hint text label. .. py:method:: set_pos_hint_text(y: float, x: float) -> None Animates the x-axis width and y-axis height of the hint text. .. py:method:: set_hint_text_font_size() -> None Animates the font size of the hint text. .. py:method:: 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. .. py:method:: set_max_text_length() -> None Fired when text is entered into a text field. Set max length text and updated max length texture. .. py:method:: adjust_height(*args) -> None Adjusts the height of the text field in multiline mode. .. py:method:: set_text(instance, text: str) -> None Fired when text is entered into a text field. .. py:method:: on_focus(instance, focus: bool) -> None Fired when the `focus` value changes. .. py:method:: on_disabled(instance, disabled: bool) -> None Fired when the `disabled` value changes. .. py:method:: on_error(instance, error: bool) -> None Changes the primary colors of the text box to match the `error` value (text field is in an error state or not). .. py:method:: on_height(instance, value_height: float) -> None