A disabled state prevents an operation that is unavailable in the current context. Use it when keeping the control visible helps people understand the task, and explain the condition that would make the action available. Do not rely on a muted appearance to provide that explanation.

Choose the state

The application decides eligibility. A disabled or hidden control is not an authorization boundary; the operation still needs application and service checks.

Choose the components

Native Button, Toggle, TextField, and TextEditor expose disabled states, but their other states and APIs differ. Button loading suppresses activation and exposes busy state while its default native button remains focusable unless also disabled. Native disabled text inputs and buttons leave the sequential tab order.

ControlGroup's disabled state affects its Button context and native fieldset behavior. Do not assume that every custom child observes the same context. Verify the actual composed controls.

Follow the interaction sequence

1. Show the unavailable action in its normal context.
2. Explain the unmet condition nearby, such as “Select a file to download.”
3. Update eligibility when the condition changes.
4. Let the person activate the action without moving focus automatically to it.
5. Replace the prerequisite explanation with progress or outcome feedback when appropriate.

If the whole task cannot proceed, provide a useful alternative, such as returning to a list or requesting access. Keep the explanation available to people who cannot focus the disabled control.

States and recovery

Do not disable the only route out of a task. If work fails, clear pending state and allow a supported retry. If availability changes while a person is interacting, preserve their input and explain the new condition.

Button rendered as an anchor uses aria-disabled and suppresses click activation, but retains its destination and remains in the tab order. Treat this separately from the default native button. See Button guidance before disabling navigation.

Content

Describe the condition in terms of the user's task: “Choose a destination to continue” is more useful than “Action disabled.” Keep essential explanations in visible text, not exclusively in a tooltip on a disabled target.

Accessibility

Disabled does not mean absent from the accessibility tree. Native disabled controls can still be encountered when reading a page with assistive technology, even though Tab skips them. Keep their labels meaningful and test the page with the intended reading and keyboard modes.

Use the component's supported state rather than applying opacity to an active control. Avoid changing focus merely because a control becomes enabled. If the currently focused element becomes unavailable, review where focus goes and provide a predictable next step.

Related implementation

See Button, Toggle, TextField, TextEditor, and ControlGroup for their individual contracts. Read Forms before choosing submission eligibility rules.

Further reading

• Apple: Buttons
• Apple: Toggles