FormFieldControl

Base class for Material form-field controls with a decorated input area.

It provides the shared label, hint, helper, error, prefix, suffix, fill, and border properties used by controls such as TextField and DropdownM2.

Inherits: LayoutControl

Properties

• align_label_with_hint - Whether the floating label should align with hint_text.
• bgcolor - TextField background color.
• border - The border drawn around the decorated input area.
• border_color deprecated - The border color.
• border_radius deprecated - Rounds the corners of an outlined border.
• border_width deprecated - The width of the border in virtual pixels.
• collapsed - Whether the decoration should be the same size as the input field.
• color - Text color.
• content_padding - The padding for the input decoration's container.
• counter - A Control to place below the line as a character count.
• counter_style - The text style to use for counter.
• dense - Whether this control is part of a dense form (ie, uses less vertical space).
• error - Text that appears below the input border.
• error_max_lines - The maximum number of lines the error can occupy.
• error_style - The text style to use for error.
• fill_color - Background color of TextField.
• filled - Whether the decoration's container is filled with fill_color.
• fit_parent_size - Whether the editable area should expand to fill the height of its parent.
• focus_color - The fill color of the decoration's container when the control has input focus.
• focused_bgcolor - Background color in focused state.
• focused_border_color deprecated - Border color in focused state.
• focused_border_width deprecated - Border width in focused state.
• focused_color - The text's color when focused.
• helper - Text that provides context about the input's value, such as how the value will be used.
• helper_max_lines - The maximum number of lines the helper can occupy.
• helper_style - The text style to use for helper.
• hint_fade_duration - The duration of the hint_text fade-in and fade-out animations.
• hint_max_lines - The maximum number of lines the hint_text can occupy.
• hint_style - The text style to use for hint_text.
• hint_text - Text that suggests what sort of input the field accepts.
• hover_color - Background color of TextField when hovered.
• icon - The icon to show before the input field and outside of the decoration's container.
• label - Optional text that describes the input field.
• label_style - The text style to use for label.
• prefix - A Control to place on the line before the input.
• prefix_icon - An icon that appears before the editable part of the text field, within the decoration's container.
• prefix_icon_size_constraints - Size constraints for the area surrounding prefix_icon.
• prefix_style - The text style to use for prefix.
• size_constraints - Defines the minimum and maximum size of the input decorator.
• suffix - A Control to place on the line after the input.
• suffix_icon - An icon that appears after the editable part of the text field and after the suffix, within the decoration's container.
• suffix_icon_size_constraints - Size constraints for the area surrounding suffix_icon.
• suffix_style - The text style to use for suffix.
• text_size - Text size in virtual pixels.
• text_style - The TextStyle to use for the text being edited.
• text_vertical_align - Defines how the text should be aligned vertically.

Methods

• focus - Request focus for this control.

Properties

buildalign_label_with_hintclass-attributeinstance-attribute

align_label_with_hint: bool | None = None

Whether the floating label should align with hint_text.

This is typically set to True for multiline text input to align the label with the top of the hint instead of centering it vertically.

buildbgcolorclass-attributeinstance-attribute

bgcolor: ColorValue | None = None

TextField background color.

Note

Will not be visible if filled is False.

buildborderclass-attributeinstance-attribute

border: ControlStateValue[InputBorder] | None = None

The border drawn around the decorated input area.

Accepts a single InputBorder or a dictionary mapping ControlStates to InputBorders. Supported state keys are ControlState.DEFAULT, ControlState.FOCUSED, ControlState.ERROR, and ControlState.DISABLED.

A single border defines the shape for all states. If its side is unset, the Material theme resolves the border color and weight per state (for example, the focused border uses the theme's primary color); an explicit side applies to the enabled state while the other states remain theme-resolved.

In the dictionary form, the DEFAULT entry behaves like the single form, and each state entry without an explicit side falls back to the DEFAULT entry's side, if set.

buildborder_colorclass-attributedeprecatedinstance-attribute

border_color: ColorValue | None = None

Deprecated

Deprecated since version 1.0.0 and scheduled for removal in 1.3.0. Use border with a BorderSide instead.

The border color.

buildborder_radiusclass-attributedeprecatedinstance-attribute

border_radius: BorderRadiusValue | None = None

Deprecated

Deprecated since version 1.0.0 and scheduled for removal in 1.3.0. Use border with an OutlineInputBorder instead.

Rounds the corners of an outlined border.

buildborder_widthclass-attributedeprecatedinstance-attribute

border_width: Number | None = None

Deprecated

Deprecated since version 1.0.0 and scheduled for removal in 1.3.0. Use border with a BorderSide instead.

The width of the border in virtual pixels.

buildcollapsedclass-attributeinstance-attribute

collapsed: bool | None = None

Whether the decoration should be the same size as the input field.

A collapsed decoration removes the extra padding normally added by the decorator.

Note

Collapsed decorations do not support label, error, counter, icon, prefix, or suffix.

buildcolorclass-attributeinstance-attribute

color: ColorValue | None = None

Text color.

buildcontent_paddingclass-attributeinstance-attribute

content_padding: PaddingValue | None = None

The padding for the input decoration's container.

buildcounterclass-attributeinstance-attribute

counter: StrOrControl | None = None

A Control to place below the line as a character count.

If None or an empty string then nothing will appear in the counter's location.

buildcounter_styleclass-attributeinstance-attribute

counter_style: TextStyle | None = None

The text style to use for counter.

builddenseclass-attributeinstance-attribute

dense: bool | None = None

Whether this control is part of a dense form (ie, uses less vertical space).

builderrorclass-attributeinstance-attribute

error: StrOrControl | None = None

Text that appears below the input border.

If non-null, the border's color animates to red and the helper is not shown.

builderror_max_linesclass-attributeinstance-attribute

error_max_lines: int | None = None

The maximum number of lines the error can occupy.

By default, soft line breaks are truncated with an ellipsis while explicit line breaks are respected. Set this property to allow long error text to wrap.

builderror_styleclass-attributeinstance-attribute

error_style: TextStyle | None = None

The text style to use for error.

buildfill_colorclass-attributeinstance-attribute

fill_color: ColorValue | None = None

Background color of TextField.

Note

Will not be visible if filled is False.

buildfilledclass-attributeinstance-attribute

filled: bool | None = None

Whether the decoration's container is filled with fill_color.

If filled=None (the default), then it is implicitly set to True when at least one of the following is not None: fill_color, focused_bgcolor, hover_color, and bgcolor.

buildfit_parent_sizeclass-attributeinstance-attribute

fit_parent_size: bool = False

Whether the editable area should expand to fill the height of its parent.

For controls that support expanding text input, such as TextField, setting this to True expands the editable area to fill the parent and clears the line count constraints.

Note

When enabled, TextField.min_lines and TextField.max_lines must effectively remain unset.

buildfocus_colorclass-attributeinstance-attribute

focus_color: ColorValue | None = None

The fill color of the decoration's container when the control has input focus.

Note

Text fields usually indicate focus by changing the focused border instead of the fill color. In Flet, prefer focused_bgcolor and a focused border state (e.g. border={ft.ControlState.FOCUSED: ft.OutlineInputBorder(...)}) when you need explicit focused-state styling.

buildfocused_bgcolorclass-attributeinstance-attribute

focused_bgcolor: ColorValue | None = None

Background color in focused state.

Note

Will not be visible if filled is False.

buildfocused_border_colorclass-attributedeprecatedinstance-attribute

focused_border_color: ColorValue | None = None

Deprecated

Deprecated since version 1.0.0 and scheduled for removal in 1.3.0. Use border with a ControlState.FOCUSED entry instead.

Border color in focused state.

buildfocused_border_widthclass-attributedeprecatedinstance-attribute

focused_border_width: Number | None = None

Deprecated

Deprecated since version 1.0.0 and scheduled for removal in 1.3.0. Use border with a ControlState.FOCUSED entry instead.

Border width in focused state.

buildfocused_colorclass-attributeinstance-attribute

focused_color: ColorValue | None = None

The text's color when focused.

buildhelperclass-attributeinstance-attribute

helper: StrOrControl | None = None

Text that provides context about the input's value, such as how the value will be used.

If non-null, the text is displayed below the input decorator, in the same location as error. If a non-null error value is specified then the helper text is not shown.

buildhelper_max_linesclass-attributeinstance-attribute

helper_max_lines: int | None = None

The maximum number of lines the helper can occupy.

buildhelper_styleclass-attributeinstance-attribute

helper_style: TextStyle | None = None

The text style to use for helper.

buildhint_fade_durationclass-attributeinstance-attribute

hint_fade_duration: DurationValue | None = None

The duration of the hint_text fade-in and fade-out animations.

buildhint_max_linesclass-attributeinstance-attribute

hint_max_lines: int | None = None

The maximum number of lines the hint_text can occupy.

buildhint_styleclass-attributeinstance-attribute

hint_style: TextStyle | None = None

The text style to use for hint_text.

buildhint_textclass-attributeinstance-attribute

hint_text: str | None = None

Text that suggests what sort of input the field accepts.

Displayed on top of the input when the it's empty and either (a) label is None or (b) the input has the focus.

buildhover_colorclass-attributeinstance-attribute

hover_color: ColorValue | None = None

Background color of TextField when hovered.

Note

Will not be visible if filled is False.

buildiconclass-attributeinstance-attribute

icon: IconDataOrControl | None = None

The icon to show before the input field and outside of the decoration's container.

buildlabelclass-attributeinstance-attribute

label: StrOrControl | None = None

Optional text that describes the input field.

When the input field is empty and unfocused, the label is displayed on top of the input field (i.e., at the same location on the screen where text may be entered in the input field). When the input field receives focus (or if the field is non-empty) the label moves above, either vertically adjacent to, or to the center of the input field.

buildlabel_styleclass-attributeinstance-attribute

label_style: TextStyle | None = None

The text style to use for label.

buildprefixclass-attributeinstance-attribute

prefix: StrOrControl | None = None

A Control to place on the line before the input.

It appears after the prefix_icon, if both are specified.

This can be used, for example, to add some padding to text that would otherwise be specified using prefix, or to add a custom control in front of the input. The control's baseline is lined up with the input baseline.

buildprefix_iconclass-attributeinstance-attribute

prefix_icon: IconDataOrControl | None = None

An icon that appears before the editable part of the text field, within the decoration's container.

If prefix is specified and visible, this icon will appear to its left.

buildprefix_icon_size_constraintsclass-attributeinstance-attribute

prefix_icon_size_constraints: BoxConstraints | None = None

Size constraints for the area surrounding prefix_icon.

This can be used to shrink or expand the default icon box. By default, the minimum width and height are 48 pixels, and tighter constraints are commonly used together with a dense decoration.

buildprefix_styleclass-attributeinstance-attribute

prefix_style: TextStyle | None = None

The text style to use for prefix.

buildsize_constraintsclass-attributeinstance-attribute

size_constraints: BoxConstraints | None = None

Defines the minimum and maximum size of the input decorator.

buildsuffixclass-attributeinstance-attribute

suffix: StrOrControl | None = None

A Control to place on the line after the input.

It appears before the suffix_icon, if both are specified.

This can be used, for example, to add some padding to the text that would otherwise be specified using suffix, or to add a custom control after the input. The control's baseline is lined up with the input baseline.

buildsuffix_iconclass-attributeinstance-attribute

suffix_icon: IconDataOrControl | None = None

An icon that appears after the editable part of the text field and after the suffix, within the decoration's container.

buildsuffix_icon_size_constraintsclass-attributeinstance-attribute

suffix_icon_size_constraints: BoxConstraints | None = None

Size constraints for the area surrounding suffix_icon.

This can be used to shrink or expand the default icon box. By default, the minimum width and height are 48 pixels, and tighter constraints are commonly used together with a dense decoration.

buildsuffix_styleclass-attributeinstance-attribute

suffix_style: TextStyle | None = None

The text style to use for suffix.

buildtext_sizeclass-attributeinstance-attribute

text_size: Number | None = None

Text size in virtual pixels.

buildtext_styleclass-attributeinstance-attribute

text_style: TextStyle | None = None

The TextStyle to use for the text being edited.

buildtext_vertical_alignclass-attributeinstance-attribute

text_vertical_align: VerticalAlignment | Number | None = (
    None
)

Defines how the text should be aligned vertically.

Value can either be a number ranging from -1.0 (topmost location) to 1.0 (bottommost location) or of type VerticalAlignment Defaults to VerticalAlignment.CENTER.

Methods

deployed_codefocusasync

focus()

Request focus for this control.

Example

async def main(page: ft.Page):
    page.add(ctf := ft.TextField())
    await ctf.focus()