> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Disabled States

## Article: Disabled States

## Article Link: https://dev.wix.com/docs/wix-design-system/guidelines/interaction-behavior/disabled-states.md

## Article Content:

<!-- heading -->

# Disabled States

<!-- end heading -->

A disabled state makes a component visible but non-interactive. It's helpful for preventing errors and guiding users, but improper use can negatively impact the user experience, cause frustration, and accessibility issues.

## 1. Key principles

**1. Informative**<br>
Users should always understand _why_ something is disabled. Clear or easy-to-find explanations help avoid confusion and give users a better sense of control over what they can do.

**2. Avoid hiding functionality**<br>
It's often better to let users attempt an action and receive real-time feedback than to hide functionality behind disabled states. Disabling elements without a clear reason can confuse and frustrate users, leaving them unsure of what to do next or where to find more information.

When used according to the guidelines, disabled states help prevent improper use of Wix products without compromising the user experience or accessibility.

## 2. Alternatives for disabled states

This section outlines common solutions you can use **instead of** disabled states to keep the experience intuitive, accessible, and informative.

### 2.1 Form validation

When users need to edit or input data before continuing, avoid disabling form actions like submit buttons. A disabled button doesn't tell users what's missing or how to fix it. It can feel like hitting a wall. Instead, keep the button active and show helpful messages after users try to submit. It's clearer, more accessible, and creates a smoother experience.

<!-- dodont -->
<!-- dodont image -->

![Do: Show contextual validation feedback on enabled buttons](https://wixmp-833713b177cebf373f611808.wixmp.com/images/6c15e537111e4df9716cc1498878cef6.gif)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Keep buttons active and show validation messages after user interaction.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![No explanation for a Disabled CTA](https://wixmp-833713b177cebf373f611808.wixmp.com/images/fad1bec02a2c2a3a453d4ea69c679a4f.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Disable buttons, especially main actions.

<!-- end dodont content -->
<!-- end dodont -->

### 2.2 Conditional relevancy

_Choose X, then show Y_

Only show options after the relevant trigger is selected. For example, don't show "Checked by default" unless "Add a checkbox" is selected. This keeps the interface clean, avoids confusing disabled elements, and helps users focus on what matters.

<br>

<!-- dodont -->
<!-- dodont image -->

![Hiding actions when they are irrelevant](https://wixmp-833713b177cebf373f611808.wixmp.com/images/1f7f44f7da8bcf51f9a8b80bfd65d043.gif)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Consider hiding actions that are only relevant when another action is taken.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Don't: Show disabled action with no context](https://wixmp-833713b177cebf373f611808.wixmp.com/images/584531b8a69cfab08cccbaaf4ed866e6.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Disable actions that depend on other conditions.

<!-- end dodont content -->
<!-- end dodont -->

### 2.3 Pre-filled fields

When a value is set elsewhere (like by the system or in another setting), don't disable the input field. Disabled fields can't be focused, copied, or read by screen readers, which can be frustrating for users. Instead, use a read-only field or plain text. This keeps the content visible and accessible, while still making it clear that the user can't edit it.

<!-- dodont -->
<!-- dodont image -->

![Read-only for input fields](https://wixmp-833713b177cebf373f611808.wixmp.com/images/ae58696f9a15413db19da02f180b0ccf.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Use read-only fields to display values that can't be changed, while keeping them selectable and accessible.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Static text instead of an input with instruction where it can be changed](https://wixmp-833713b177cebf373f611808.wixmp.com/images/f4c6572aeb5b1e64ffd9c9f599f4528c.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Use static text instead of inputs. If necessary, explain where the value can be changed.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Use disabled inputs for read-only content](https://wixmp-833713b177cebf373f611808.wixmp.com/images/5af69ec76a89b4d64d253179e265dc2b.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Disable inputs when read-only or static content is clearer.

<!-- end dodont content -->
<!-- end dodont -->

### 2.4 Loading

When content is loading, use loading indicators to show progress and prevent repeated clicks.

<!-- dodont -->
<!-- dodont image -->

![Loading state of a button](https://wixmp-833713b177cebf373f611808.wixmp.com/images/fcba41aa4eaa56dd97beba4e6d4514d6.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Show a loader or message like "Saving...".

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Loading state of a disabled button](https://wixmp-833713b177cebf373f611808.wixmp.com/images/8d03bf01b0aab1ef6660a39058dc9419.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Disable the element, but don't let users click on actions while content is still processing.

<!-- end dodont content -->
<!-- end dodont -->

For more about loading states you can read the [Notification and states guidelines](#/page/guidelines/statemanagement)

## 3. How to use disabled states

This section provides solutions for when disabled states **can be** used. The primary goal is to ensure our users understand why it is disabled and what they can do to make the element active.

### 3.1 Section helpers

This solution is flexible and can be used for page sections, like a whole card, or sections in that card. The primary goal is to tell the user how to activate the section (for example, To do \_**\_, do \_\_**).

<!-- dodont -->
<!-- dodont image -->

![Using section helper to explain disabled elements](https://wixmp-833713b177cebf373f611808.wixmp.com/images/3e9b7d2f6730436f59ff2b00f50b979f.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Use section helpers to explain why content is disabled and how users can update it. In this example, the "Inventory & pre-order" section is disabled and the helper section explains that the inventory can be edited in the third party app, UpperApp.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Using section helper to explain disabled elements](https://wixmp-833713b177cebf373f611808.wixmp.com/images/47d2a6092a71fd28ff4c0517a48ae5c7.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Use section helpers to explain why a smaller group of elements inside a larger section is disabled.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Tooltip that doesn't explain the disabled state](https://wixmp-833713b177cebf373f611808.wixmp.com/images/cb17e8227ae4f902670f9d07775db107.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Position a section helper in a way that makes it seem like the whole card is disabled when only one element is disabled. Instead, position the helper section close to the specific element it addresses.

<!-- end dodont content -->
<!-- end dodont -->

### 3.2 Status messages

This solution can be used when space allows for more text on screen. It is useful when explaining why smaller elements that are disabled (for example, toggles, checkboxes, input fields).

<!-- dodont -->
<!-- dodont image -->

![Status message to explain Premium and guide user](https://wixmp-833713b177cebf373f611808.wixmp.com/images/270d2fd949447142cef5ad696551f9fb.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Use status messages to identify Premium features and provide an upgrade path.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Explain disabled control due to permissions](https://wixmp-833713b177cebf373f611808.wixmp.com/images/d770591ceea9bc45934313b473846331.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Use status messages to explain why elements are restricted and explain how users can access them.

<!-- end dodont content -->
<!-- end dodont -->

### 3.3 Info icons

Info icons can be used to explain a disabled state to users (for example, tables, lists).

<!-- dodont -->
<!-- dodont image -->

![Info icon to explain disabled toggle](https://wixmp-833713b177cebf373f611808.wixmp.com/images/88256841a1f8a33b1b9febb1fda4ce56.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Info icons next to disabled elements can help clarify the state to users.

<!-- end dodont content -->
<!-- end dodont -->

### 3.4 Tooltips

When there is no other optimal way to explain the disabled state to users, provide tooltips on hover and focus. However, be mindful that this approach has accessibility limitations and may not work well for all users.

<!-- dodont -->
<!-- dodont image -->

![Do: Show contextual validation feedback on enabled buttons](https://wixmp-833713b177cebf373f611808.wixmp.com/images/37933e205d7899be39a3f3def44290d9.gif)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Indicate why an element is disabled in a tooltip on hover and focus.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Show disabled action with no context](https://wixmp-833713b177cebf373f611808.wixmp.com/images/6898bfe151d6b02d0ce9c5557018adef.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Leave the user without explaining how they can activate the element.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Tooltip that doesn't explain the disabled state](https://wixmp-833713b177cebf373f611808.wixmp.com/images/9dbed4f35a26089c46b9f2830194439c.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Use tooltips that fail to guide users on how to activate the element.

<!-- end dodont content -->
<!-- end dodont -->

When tooltips are used on multiple items that are close together, apply a delay to avoid overwhelming the user. Use the `enterDelay` token to control when the tooltip appears, so it doesn't pop up too quickly or block nearby content.

<!-- dodont -->
<!-- dodont image -->

![Explain disabled control due to permissions](https://wixmp-833713b177cebf373f611808.wixmp.com/images/afaff332809c6acdcc8c285ed7d741b9.gif)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

When using a tooltip to explain a disabled state, consider applying a delay to it.

<!-- end dodont content -->
<!-- end dodont -->

### 3.5 Step-by-step flows

In a step-by-step flow, use disabled states to block steps (for example, Step 2, 3), but allow navigation and provide feedback when necessary.

<!-- dodont -->
<!-- dodont image -->

![Do: Validate before next step](https://wixmp-833713b177cebf373f611808.wixmp.com/images/41cfd514c937313420bea912084fbb21.gif)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Allow users to go to the next steps and provide feedback when errors occur. When suitable, indicate fields that contain errors.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Don't: Disable steps with no visible issues](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e0534627e9754bda67568b0d1a494b47.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Disable navigation without clearly showing what must be done, this blocks the user.

<!-- end dodont content -->
<!-- end dodont -->

### 3.6 Contextual utilities

For actions like "Revert" or "Clear," we recommend using disabled states as they indicate that such actions are available, but currently it's disabled.

<!-- dodont -->
<!-- dodont image -->

![Navigation is enabled, but shows validation error](https://wixmp-833713b177cebf373f611808.wixmp.com/images/f9e20749c85d99471885afc28c367b5b.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Show disabled elements, but also show tooltips to explain them.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Navigation disabled without context](https://wixmp-833713b177cebf373f611808.wixmp.com/images/b168ae5c7c66cacc201191f001214ac5.png)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Remove elements from the page, while also shifting the layout of the page.

<!-- end dodont content -->
<!-- end dodont -->

## 4. Accessibility

Disabled states present several accessibility challenges, and care must be taken to ensure all users understand what's happening.

**1. `aria-disabled`**
Make sure screen readers are aware of disabled elements. Use `aria-disabled=true`, and ensure elements can still be focused or announced.

**2. `aria-describedby`**
Point to a visible explanation when context isn't next to the component.

**3. Use read-only when appropriate**
If users still need the information (for example, to copy it), use read-only or static display instead.

**4. Don't rely on color alone**
Color alone isn't enough to signal disabled status. Use text cues, iconography, and `cursor: not-allowed` for added clarity.

<!-- dodont -->
<!-- dodont image -->

![Do: Explain disabled control due to permissions](https://wixmp-833713b177cebf373f611808.wixmp.com/images/17e77cfdc6a0ddfa75887153c1694090.gif)

<!-- end dodont image -->
<!-- dodont content -->

#### Do

Apply aria-disabled to important elements. This allows keyboard navigation.

<!-- end dodont content -->
<!-- end dodont -->

<br>

<!-- dodont -->
<!-- dodont image -->

![Don't: Disable without clarity](https://wixmp-833713b177cebf373f611808.wixmp.com/images/347af67aa958106cc60d34927a7dd0c5.gif)

<!-- end dodont image -->
<!-- dodont content -->

#### Don't

Leave important elements non-interactive. Keyboard navigation often skips disabled elements.

<!-- end dodont content -->
<!-- end dodont -->

---

## Related components

- [Form field](#/component/formfield)
- [Tooltip](#/component/tooltip)
- [Section helper](#/component/sectionhelper)