ControlState

Inherits: Enum

Interactive states that some controls can take on when receiving input from the user.

States are defined by the Material 3 design specification, but are not limited to it.

Not all states are always applicable to all controls.

Properties

• DEFAULT –

  The default state. Will be used for undeclared states.

• DISABLED –

  The state when this control is disabled and cannot be interacted with.

• DRAGGED –

  The state when this control is being dragged from one place to another by the user.

• ERROR –

  The state when the control has entered some form of invalid state.

• FOCUSED –

  The state when the user navigates with the keyboard to a given control.

• HOVERED –

  The state when the user drags their mouse cursor over the given control.

• PRESSED –

  The state when the user is actively pressing down on the given control.

• SCROLLED_UNDER –

  The state when this control overlaps the content of a scrollable below.

• SELECTED –

  The state when this item has been selected.

Properties

DEFAULT class-attribute instance-attribute

DEFAULT = 'default'

The default state. Will be used for undeclared states.

DISABLED class-attribute instance-attribute

DISABLED = 'disabled'

The state when this control is disabled and cannot be interacted with.

Disabled controls should not respond to hover, focus, press, or drag interactions.

See material docs.

DRAGGED class-attribute instance-attribute

DRAGGED = 'dragged'

The state when this control is being dragged from one place to another by the user.

See material docs.

ERROR class-attribute instance-attribute

ERROR = 'error'

The state when the control has entered some form of invalid state.

See material docs.

FOCUSED class-attribute instance-attribute

FOCUSED = 'focused'

The state when the user navigates with the keyboard to a given control.

This can also sometimes be triggered when a control is tapped. For example, when a [TextField] is tapped, it becomes FOCUSED.

See material docs.

HOVERED class-attribute instance-attribute

HOVERED = 'hovered'

The state when the user drags their mouse cursor over the given control.

See material docs.

PRESSED class-attribute instance-attribute

PRESSED = 'pressed'

The state when the user is actively pressing down on the given control.

See material docs.

SCROLLED_UNDER class-attribute instance-attribute

SCROLLED_UNDER = 'scrolledUnder'

The state when this control overlaps the content of a scrollable below.

Used by AppBar to indicate that the primary scrollable's content has scrolled up and behind the app bar.

SELECTED class-attribute instance-attribute

SELECTED = 'selected'

The state when this item has been selected.

This applies to things that can be toggled (such as chips and checkboxes) and things that are selected from a set of options (such as tabs and radio buttons).

See material docs.

Usage Example

Configuring fill_color can be done in two ways:

1. Single Value for All States

If you want to use the same color across all Material states, simply assign fill_color to a single color:

ft.Radio(fill_color=ft.Colors.GREEN)

2. Specific Values for Each State

For more control, you can provide a dictionary where the key is the state name and the value is the corresponding color.

Ordering Matters

• The order in which states appear in the dictionary will determine their priority, allowing for flexibility and customization.
• The position of DEFAULT does not affect behavior—it always has the least priority and can be placed anywhere in the dictionary.

Example

To configure different fill colors of a Radio button for ControlState.HOVERED and ControlState.FOCUSED, with a fallback color for all other states:

ft.Radio(
    fill_color={
        ft.ControlState.HOVERED: ft.Colors.GREEN,
        ft.ControlState.FOCUSED: ft.Colors.RED,
        ft.ControlState.DEFAULT: ft.Colors.BLACK,
    }
)

This setup ensures that HOVERED and FOCUSED states take precedence, while all unspecified states default to BLACK.