> For the complete documentation index, see [llms.txt](https://docs.webstudio.is/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webstudio.is/university/foundations/states-and-selectors.md).

# States and selectors

Style elements differently based on user interaction (hover, focus, active) or target virtual parts of an element (::before, ::after) using states and selectors.

States and selectors let you apply styles conditionally — for example, change a button's color on hover, or add decorative content with `::before`.

They live in the **Style Sources** dropdown alongside your [Tokens](https://docs.webstudio.is/university/foundations/design-tokens.md). Open it by clicking the Style Sources area above the Style Panel or pressing `⌘ + Enter` (Mac) / `Ctrl + Enter` (Windows).

<figure><picture><source srcset="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-a04e0c1a67532b5fed3c77dd1058ecb451762b7c%2Fstates-dropdown-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-e2026d10d1c0825fd1dd9abf28a8d4b4fd55765e%2Fstates-dropdown-light.png?alt=media" alt="Style Sources dropdown listing hover, focus, and active states" width="240"></picture><figcaption><p>Available states appear at the bottom of the Style Sources dropdown</p></figcaption></figure>

## States (pseudo-classes)

States are CSS pseudo-classes that apply styles when a condition is true, such as the user hovering over an element.

### Adding a state

1. Select an instance on the canvas.
2. Open the Style Sources dropdown (`⌘ + Enter`).
3. Choose a state from the list at the bottom, or type one in.
4. The state appears as a tag in the style sources area. While it's active, every style you set applies only to that state.
5. Click the state tag again to deselect it and return to the base (default) styles.

<figure><picture><source srcset="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-ca18a23e7bc6feb53396f1f2c1ae78a7218f9a1f%2Fstate-active-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-42db2aaa9b5de6b61034e9371fd369582b095c32%2Fstate-active-light.png?alt=media" alt="Style sources field with the hover state selected" width="240"></picture><figcaption><p>The :hover state is selected — styles set now only apply on hover</p></figcaption></figure>

### Custom states

Use **Add more** in a Tag, Token, or Local style source to enter a selector that is not in the list.

{% hint style="info" %}
Start with `:` or `[` to target the current source's element or its pseudo-elements. For example, `:hover` applies while the element is hovered, `[data-state=open]` applies when its attribute matches, and `::before` targets its pseudo-element. You can combine conditions, such as `[data-state=open]:hover`.

Start with an HTML tag name to style that tag nested inside the current source's element. For example, `h2`, `h2:hover`, `h2[a="123"]`, and `h2::before` target nested headings. Quote numeric attribute values as in `a="123"`. A [Tag style](https://docs.webstudio.is/university/foundations/tag-styles.md) applies its nested tag selector across the site; a Token or Local source applies it only where that source is used.

You can also start with a state on the source's element, then target a descendant class. For example, `:hover .button` targets descendants with the [custom class](https://docs.webstudio.is/university/foundations/custom-classes-and-attributes.md) `button` while the source's element is hovered. `:hover > .icon` targets only direct children with class `icon`. These work in Tag, Token, and Local sources, with each source's usual scope.

**Add more** does not accept multiple top-level selectors or unanchored class and ID selectors such as `.card`. A nested tag selector accepts one tag with optional conditions; a state-based descendant selector begins with a state on the source's element.
{% endhint %}

## Pseudo-elements

Pseudo-elements target virtual parts of an element, such as inserting content before or after it, or styling the first letter.

### Adding a pseudo-element

1. Select an instance.
2. Open the Style Sources dropdown (`⌘ + Enter`).
3. Type `::before`, `::after`, or another pseudo-element — autocomplete will suggest matches.
4. The pseudo-element appears as a tag. While selected, styles apply to that virtual element.

<figure><picture><source srcset="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-a89a2d4a64211e17267cf7aaddf4f1d72fcf703d%2Fpseudo-element-autocomplete-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-413e2bdcadddeda0bc54b53a12a8b1d9176a4bd2%2Fpseudo-element-autocomplete-light.png?alt=media" alt="Pseudo-element suggestions filtered by typing ::b, including ::before" width="240"></picture><figcaption><p>Type :: to see available pseudo-elements</p></figcaption></figure>

### Common pseudo-elements

| Pseudo-element   | What it targets                             |
| ---------------- | ------------------------------------------- |
| `::before`       | Virtual element inserted before the content |
| `::after`        | Virtual element inserted after the content  |
| `::placeholder`  | Placeholder text in inputs and textareas    |
| `::selection`    | Text selected/highlighted by the user       |
| `::first-letter` | First letter of a block element             |
| `::first-line`   | First line of a block element               |
| `::marker`       | Bullet or number of a list item             |
| `::backdrop`     | Box behind a fullscreen or modal element    |

{% hint style="info" %}
`::before` and `::after` require a `content` value to be visible. Set it in the **Advanced** section — even an empty string (`""`) works.
{% endhint %}

### Example: decorative element with ::before

1. Select a Box, Link, or Button.
2. Add `::before` via the Style Sources dropdown.
3. In the **Advanced** section, set `content` to `""`.
4. Set `display` to `block` and give it a width, height, and background.
5. Deselect the `::before` tag to go back to the base styles.

<figure><picture><source srcset="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-a1ea7a9f2f9bbdef2be84e0267af832568a84a7a%2Fbefore-example-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://330243581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTep4EGj6hSC54ozHujyK%2Fuploads%2Fgit-blob-0890dad96a8bb6764e80346d05d50232834c6b5b%2Fbefore-example-light.png?alt=media" alt="Style sources with the ::before pseudo-element selected" width="240"></picture><figcaption><p>Select ::before to edit its styles</p></figcaption></figure>

## Combining states and tokens

States work together with [Tokens](https://docs.webstudio.is/university/foundations/design-tokens.md). When you have a Token selected, adding a state applies styles for that state *within that Token*. This keeps hover styles, focus styles, and base styles neatly organized.

You can also use [CSS variables](https://docs.webstudio.is/university/foundations/css-variables.md) to coordinate several parent-child style changes — define variables on the parent, then change their values on the `:hover` state so all children update at once. See [Parent-child interactions](https://docs.webstudio.is/university/foundations/css-variables.md#parent-child-interactions) for details.

## Related

* [CSS variables](https://docs.webstudio.is/university/foundations/css-variables.md) – Define reusable values and create parent-child hover interactions
* [Design tokens](https://docs.webstudio.is/university/foundations/design-tokens.md) – Package multiple styles for reuse
* [Anatomy of the Webstudio builder](https://docs.webstudio.is/university/foundations/anatomy-of-the-webstudio-builder.md) – Learn about the Style Panel and Style Sources
* [Shortcuts](https://docs.webstudio.is/university/foundations/shortcuts.md) – Keyboard shortcuts including `⌘ + Enter` for Style Sources


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.webstudio.is/university/foundations/states-and-selectors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
