0
# Text & Input Components
1
2
Text display and input components that follow Material Design specifications for typography, text fields, and selection controls. These components provide consistent text styling, input validation, and interaction patterns across the application.
3
4
## Capabilities
5
6
### Text Display
7
8
Components for displaying text with Material Design typography and theming.
9
10
```python { .api }
11
class MDLabel:
12
"""
13
Material Design label for displaying text.
14
15
Text display widget that follows Material Design typography guidelines
16
with automatic theming and font styling.
17
"""
18
text: str # Label text content
19
theme_text_color: str # Text color theme: "Primary", "Secondary", "Hint", "Error", "Custom"
20
text_color: list # Custom text color as RGBA
21
font_style: str # Font style: "H1", "H2", "H3", "H4", "H5", "H6", "Subtitle1", "Subtitle2", "Body1", "Body2", "Button", "Caption", "Overline"
22
halign: str # Horizontal alignment: "left", "center", "right", "justify"
23
valign: str # Vertical alignment: "top", "middle", "bottom"
24
markup: bool # Enable markup text formatting
25
26
class MDIcon:
27
"""
28
Material Design icon display widget.
29
30
Displays Material Design icons with consistent sizing and theming.
31
"""
32
icon: str # Icon name from md_icons dictionary
33
theme_icon_color: str # Icon color theme: "Primary", "Secondary", "Hint", "Error", "Custom"
34
icon_color: list # Custom icon color as RGBA
35
user_font_size: str # Icon size (e.g., "24sp", "32sp")
36
37
def set_icon(self, icon_name: str):
38
"""
39
Set the displayed icon.
40
41
Args:
42
icon_name (str): Icon name from md_icons dictionary
43
"""
44
```
45
46
### Text Input Fields
47
48
Text input components with Material Design styling, validation, and helper text.
49
50
```python { .api }
51
class MDTextField:
52
"""
53
Material Design text input field.
54
55
Text input widget with Material Design styling including floating labels,
56
helper text, error states, and validation.
57
"""
58
text: str # Current text content
59
hint_text: str # Placeholder text when field is empty
60
helper_text: str # Helper text displayed below field
61
helper_text_mode: str # Helper text mode: "none", "on_focus", "persistent", "on_error"
62
63
# Validation and error states
64
error: bool # Error state flag
65
required: bool # Required field flag
66
text_validate_unfocus: bool # Validate on unfocus
67
68
# Text formatting
69
multiline: bool # Allow multiple lines
70
password: bool # Password field (hidden text)
71
input_filter: str # Input filter: "int", "float", None
72
73
# Visual styling
74
mode: str # Field mode: "line", "rectangle", "fill"
75
line_color_normal: list # Normal line color
76
line_color_focus: list # Focus line color
77
fill_color_normal: list # Normal fill color
78
fill_color_focus: list # Focus fill color
79
80
# Sizing
81
max_text_length: int # Maximum text length
82
font_size: str # Font size (e.g., "14sp")
83
84
def on_text_validate(self):
85
"""Called when text is validated (Enter pressed)."""
86
87
def on_focus(self, instance, focus: bool):
88
"""Called when focus changes."""
89
90
class MDTextFieldRect:
91
"""
92
Rectangular Material Design text field.
93
94
Text field with rectangular border styling instead of underline.
95
"""
96
text: str # Current text content
97
hint_text: str # Placeholder text
98
multiline: bool # Allow multiple lines
99
readonly: bool # Read-only mode
100
101
# Styling
102
normal_color: list # Normal border color
103
focus_color: list # Focus border color
104
line_width: float # Border line width
105
```
106
107
### Selection Controls
108
109
Input controls for user selection including checkboxes, switches, and sliders.
110
111
```python { .api }
112
class MDCheckbox:
113
"""
114
Material Design checkbox.
115
116
Binary selection control with Material Design styling and animations.
117
"""
118
active: bool # Checkbox state (checked/unchecked)
119
disabled: bool # Disabled state
120
checkbox_icon_normal: str # Unchecked icon
121
checkbox_icon_down: str # Checked icon
122
123
# Colors
124
selected_color: list # Selected state color
125
unselected_color: list # Unselected state color
126
disabled_color: list # Disabled state color
127
128
def on_active(self, instance, active: bool):
129
"""Called when checkbox state changes."""
130
131
class MDSwitch:
132
"""
133
Material Design switch.
134
135
Toggle switch for binary on/off states with smooth animations.
136
"""
137
active: bool # Switch state (on/off)
138
disabled: bool # Disabled state
139
140
# Visual properties
141
thumb_color_active: list # Active thumb color
142
thumb_color_inactive: list # Inactive thumb color
143
track_color_active: list # Active track color
144
track_color_inactive: list # Inactive track color
145
146
def on_active(self, instance, active: bool):
147
"""Called when switch state changes."""
148
149
class Thumb:
150
"""
151
Thumb component for switches.
152
153
Visual thumb element that slides along the switch track.
154
"""
155
156
class MDSlider:
157
"""
158
Material Design slider.
159
160
Continuous selection control for choosing values from a range.
161
"""
162
value: float # Current slider value
163
min: float # Minimum value
164
max: float # Maximum value
165
step: float # Value increment step
166
167
# Visual styling
168
color: list # Slider color
169
track_color_active: list # Active track color
170
track_color_inactive: list # Inactive track color
171
thumb_color_active: list # Active thumb color
172
thumb_color_inactive: list # Inactive thumb color
173
174
# Display options
175
show_off: bool # Show value when not active
176
hint: bool # Show hint bubble with value
177
178
def on_value(self, instance, value: float):
179
"""Called when slider value changes."""
180
```
181
182
## Usage Examples
183
184
### Basic Text Display
185
186
```python
187
from kivymd.uix.label import MDLabel, MDIcon
188
from kivymd.uix.boxlayout import MDBoxLayout
189
190
# Create layout
191
layout = MDBoxLayout(
192
orientation="vertical",
193
spacing="16dp",
194
adaptive_height=True,
195
padding="16dp"
196
)
197
198
# Title label
199
title = MDLabel(
200
text="Material Design App",
201
font_style="H4",
202
theme_text_color="Primary",
203
halign="center"
204
)
205
206
# Body text
207
body = MDLabel(
208
text="This is body text using Material Design typography.",
209
font_style="Body1",
210
theme_text_color="Primary",
211
halign="center"
212
)
213
214
# Icon
215
icon = MDIcon(
216
icon="heart",
217
theme_icon_color="Error",
218
user_font_size="48sp",
219
pos_hint={"center_x": 0.5}
220
)
221
222
layout.add_widget(title)
223
layout.add_widget(body)
224
layout.add_widget(icon)
225
```
226
227
### Text Input Form
228
229
```python
230
from kivymd.uix.textfield import MDTextField
231
from kivymd.uix.boxlayout import MDBoxLayout
232
from kivymd.uix.button import MDRaisedButton
233
234
# Create form layout
235
form = MDBoxLayout(
236
orientation="vertical",
237
spacing="16dp",
238
adaptive_height=True,
239
padding="16dp"
240
)
241
242
# Name field
243
name_field = MDTextField(
244
hint_text="Enter your name",
245
helper_text="Required field",
246
helper_text_mode="persistent",
247
required=True,
248
mode="rectangle"
249
)
250
251
# Email field
252
email_field = MDTextField(
253
hint_text="Enter your email",
254
helper_text="We'll never share your email",
255
helper_text_mode="on_focus",
256
input_filter=None, # Could add email validation
257
mode="rectangle"
258
)
259
260
# Password field
261
password_field = MDTextField(
262
hint_text="Enter password",
263
helper_text="Minimum 8 characters",
264
password=True,
265
mode="rectangle"
266
)
267
268
# Submit button
269
submit_button = MDRaisedButton(
270
text="Submit",
271
pos_hint={"center_x": 0.5}
272
)
273
274
form.add_widget(name_field)
275
form.add_widget(email_field)
276
form.add_widget(password_field)
277
form.add_widget(submit_button)
278
```
279
280
### Selection Controls
281
282
```python
283
from kivymd.uix.selectioncontrol import MDCheckbox, MDSwitch
284
from kivymd.uix.slider import MDSlider
285
from kivymd.uix.boxlayout import MDBoxLayout
286
from kivymd.uix.label import MDLabel
287
288
# Create controls layout
289
controls = MDBoxLayout(
290
orientation="vertical",
291
spacing="24dp",
292
adaptive_height=True,
293
padding="16dp"
294
)
295
296
# Checkbox
297
checkbox = MDCheckbox(
298
active=False,
299
size_hint=(None, None),
300
size=("48dp", "48dp"),
301
pos_hint={"center_x": 0.5}
302
)
303
checkbox_label = MDLabel(
304
text="Accept terms and conditions",
305
theme_text_color="Primary"
306
)
307
308
# Switch
309
switch = MDSwitch(
310
active=True,
311
pos_hint={"center_x": 0.5}
312
)
313
switch_label = MDLabel(
314
text="Enable notifications",
315
theme_text_color="Primary"
316
)
317
318
# Slider
319
slider = MDSlider(
320
min=0,
321
max=100,
322
value=50,
323
step=1,
324
hint=True,
325
size_hint_x=0.8,
326
pos_hint={"center_x": 0.5}
327
)
328
slider_label = MDLabel(
329
text="Volume",
330
theme_text_color="Primary"
331
)
332
333
# Add to layout
334
controls.add_widget(checkbox_label)
335
controls.add_widget(checkbox)
336
controls.add_widget(switch_label)
337
controls.add_widget(switch)
338
controls.add_widget(slider_label)
339
controls.add_widget(slider)
340
```
341
342
### Text Field Validation
343
344
```python
345
from kivymd.uix.textfield import MDTextField
346
347
class ValidatedTextField(MDTextField):
348
def __init__(self, **kwargs):
349
super().__init__(**kwargs)
350
self.bind(text=self.on_text_change)
351
352
def on_text_change(self, instance, text):
353
"""Validate text input."""
354
if self.required and not text.strip():
355
self.error = True
356
self.helper_text = "This field is required"
357
elif len(text) < 3:
358
self.error = True
359
self.helper_text = "Minimum 3 characters required"
360
else:
361
self.error = False
362
self.helper_text = "Looks good!"
363
364
# Usage
365
validated_field = ValidatedTextField(
366
hint_text="Username",
367
required=True,
368
helper_text_mode="persistent",
369
mode="rectangle"
370
)
371
```