[animation-triggers-1] Proposal: toggle Custom States using Animation Triggers (`state-trigger`)

[ydaniv]

Summary

This proposal introduces a new CSS property, state-trigger, that leverages the animation trigger infrastructure to toggle custom states on elements declaratively. Building on the proposal to expand :state() to all elements, this would allow authors to add or remove custom states based on scroll position, visibility, or user-interaction events.

Motivation

The gap between triggers and styling

The animation trigger specification (animation-triggers-1) defines a powerful model of timeline triggers and event triggers that can control animation playback based on scroll position, viewport entry, clicks, and other interactions.

However, there are many use cases where the desired reaction to a trigger is not an animation, but a state change — toggling a class-like flag on an element so that different CSS rules can apply. Today, this requires JavaScript event listeners or IntersectionObservers to add/remove classes or custom states.

Custom states are the right primitive

CSS custom states (:state()) provide a mechanism for elements to expose named boolean states that can be matched by CSS selectors. They are already supported for custom elements via ElementInternals.states (CustomStateSet), and there is an active proposal to expand Element.prototype.states to all elements.

By combining triggers with custom states, we can enable a broad class of declarative, CSS-only interactions that currently require JavaScript.

Use cases

• Scroll-triggered state: Mark an element as :state(--visible) when it enters the viewport, enabling CSS-only reveal effects, lazy styling, or conditional layouts.

• Sticky header detection: Set :state(--stuck) on a sticky element when it reaches its sticking position, enabling shadow/border changes.

• Interaction-driven toggles: Toggle :state(--active) on click (and untoggle on a second click), enabling accordion, tab, or disclosure patterns.

• Reading progress markers: Mark table-of-contents items as :state(--read) as corresponding sections scroll past, enabling progress indicators.

• Hover/focus persistence: Set :state(--was-hovered) that persists after the pointer leaves, enabling "seen" indicators or progressive disclosure.

Proposed Solution

New property: state-trigger

A new shorthand property state-trigger connects a named trigger to the element it is specified on, with dedicated actions that modify the element's custom state set. This new property is a coordinated list property, allowing to set multiple triggers.

state-trigger: [ [ <dashed-ident> <state-action>+ ]+ ]#

Where:

• <dashed-ident> references a named trigger (defined via timeline-trigger or event-trigger on some element)
• <state-action> specifies what state modifications to perform when the trigger activates

The <state-action> type

<state-action> = add-state(<dashed-ident>) | remove-state(<dashed-ident>) | toggle-state(<dashed-ident>) | none

• add-state(<dashed-ident>) — Adds the specified custom state to the element's state set.
• remove-state(<dashed-ident>) — Removes the specified custom state from the element's state set.
• toggle-state(<dashed-ident>) — Adds the state if absent, removes it if present.

Note: another option is to use custom-idents instead if there’s no risk of name clash and we can achieve a similar syntax to custom states currently used in JS.

Like animation-trigger, trigger types that support two actions (stateful event triggers and timeline triggers) accept one or two <state-action> values: the first for the entry/activation action, the second for the exit/deactivation action.

Full property definition

Name: state-trigger
Value: [ none | [ <dashed-ident> <state-action>+ ]+ ]#
Initial: none
Applies to: all elements
Inherited: no
Animation type: not animatable

Examples

Viewport entry — element becomes :state(--visible)

/* Define a timeline trigger on the element itself */
.reveal {
  timeline-trigger: --on-screen view();
  state-trigger: --on-screen add-state(--visible);
}

/* Style based on the custom state — no animation needed */
.reveal {
  opacity: 0;
  transition: opacity 0.5s;
}
.reveal:state(--visible) {
  opacity: 1;
}

Viewport entry/exit — toggle a state

.card {
  timeline-trigger: --in-view view() entry 25% entry 75%;
  state-trigger: --in-view add-state(--in-view) remove-state(--in-view);
}

.card:state(--in-view) {
  outline: 2px solid highlight;
}

Click toggle — accordion pattern

.accordion-header {
  event-trigger: --toggle click;
  state-trigger: --toggle toggle-state(--open);
}

.accordion-header + .accordion-body {
  display: none;
}
.accordion-header:state(--open) + .accordion-body {
  display: block;
}

Hover persistence

.tooltip-trigger {
  event-trigger: --seen pointerenter;
  state-trigger: --seen add-state(--was-hovered);
}

.tooltip-trigger:state(--was-hovered)::after {
  content: "✓ Seen";
}

Interaction with existing specs

Trigger resolution

state-trigger uses the same trigger name resolution mechanism as animation-trigger (see trigger-scope). The <dashed-ident> in state-trigger references a trigger by name, following the same scoping rules.

Trigger actions model

The trigger infrastructure in animation-triggers-1 is designed to be generic — as noted in the spec:

"This design for triggers and trigger instances, and the way they're associated with triggered animations and <animation-action>s, is intentionally somewhat generic, intended to support using triggers for other purposes in the future."

state-trigger is a natural second consumer of this infrastructure, alongside animation-trigger. Where animation-trigger maps trigger activations to animation playback actions (play, pause, reset, etc.), state-trigger maps them to state mutations (add-state, remove-state, toggle-state).

Dependency on expanded :state()

This proposal depends on custom states being settable on all elements, not just custom elements. This aligns with whatwg/html#11466, which proposes Element.prototype.states. Without this expansion, state-trigger would only be useful on custom elements — significantly limiting its value.

Prior Art

CSS Toggles was a proposal for declarative state management in CSS. state-trigger differs from the Toggles proposal by specifically connecting the trigger infrastructure to custom element states, reusing existing trigger and :state() primitives.

The CSS Toggles proposal had a more elaborate set of state management actions that could be borrowed if necessary. This proposal focuses on the simpler, more narrowly scoped integration with :state().

API extension (imperative)

Using the imperative API in animation-triggers-1 for creating triggers can probably be reused here for toggling custom states, and this would allow creating state triggers programmatically, though the primary motivation for this proposal is the declarative CSS API.

Open issues/questions

• A11y concerns in general - assuming declaring state change based on interactions that is only declared by CSS is currently problematic? Can we solve this in the internally in the UA? Perhaps with additional HTML aria attributes?
• All names are bikeshedable.
• Whether to use custom-ident or dashed-ident in <state-action>.
• Whether we want a dedicated imperative API for this feature.

---

/cc @flackr @DavMila @LeaVerou @tabatkins @mirisuzanne

[flackr]

I think you can set up generic state-like changes with animation triggers with something like this:

@keyframes state-foo { to {--state: foo;} }
.target {
  animation: state-foo forwards;
  animation-trigger: --in-view;
  timeline-trigger: --in-view view();
  @container style(--state: foo) {
    /* Style descendants after state change */
  }
}

[css-meeting-bot]

The CSS Working Group just discussed [animation-triggers-1] Proposal: toggle Custom States using Animation Triggers (`state-trigger`).

The full IRC log of that discussion

<TabAtkins> ydaniv: we've started work on animation-triggers. have timeline-trigger in chrome, working on event-trigger
<TabAtkins> ydaniv: these only allow us to change animation playback
<TabAtkins> ydaniv: there was previously work on state management with triggers, using CSS toggles. this didn't mature into an accepted proposal
<TabAtkins> ydaniv: this is trying to revive a similar concept, but building on things we already have accepted, like animation-triggers
<TabAtkins> ydaniv: idea is simple. we already have element stages, select via :state(), for custom elements
<TabAtkins> ydaniv: using JS you can add/remove strings from the state set, changes how :state() matches
<TabAtkins> ydaniv: proposal from Lea to extend this fucntional pseudo to all elements
<flackr> q+
<TabAtkins> ydaniv: building on that, this proposal suggests using triggers to have additional actions, a new property state-trigger
<TabAtkins> ydaniv: jumping to examples, lets you connect the name of a trigger and adjust states
<TabAtkins> ydaniv: `timeline-trigger: --on-screen view(); state-trigger: --on-screen add-state(--visible);`
<TabAtkins> ydaniv: then `:state(--visible)` will work
<lea> q+
<TabAtkins> ydaniv: today people use classes for this, or custom elements. this connects all of this together into a declarative api
<TabAtkins> ydaniv: proposal for three new actions - add-state(), remove-state(), toggle-state()
<TabAtkins> ydaniv: could also trigger these via an event-trigger
<TabAtkins> ydaniv: today you'd hack around this with animation triggers, or container state queries, etc.
<TabAtkins> ydaniv: so i think this i smore straightforward for binding these together
<TabAtkins> ydaniv: some open issues
<TabAtkins> ydaniv: biggest from a convo yesterday was there might be big a11y concerns, same as css toggle
<TabAtkins> ydaniv: but since people can do all this today with JS, probably still worth solving easier rather than blocking
<kbabbitt> q+
<TabAtkins> ydaniv: everything is bikesheddable
<TabAtkins> ydaniv: some questions about custom-ident vs dashed-ident...
<TabAtkins> ydaniv: whether we want later an imperative API like we have for animation triggers
<TabAtkins> q+
<Rossen> ack flackr
<TabAtkins> flackr: i believe this can be completely done with triggers and fill-forward animations, especially a once() trigger
<TabAtkins> flackr: so given that, is there a big ergonomic advantage to adding new stuff
<Rossen> ack lea
<TabAtkins> flackr: two, would like to see how people would buiold it today, don't thin kit's that much harder and i think it would help inform future solutions
<TabAtkins> lea: might have missed it - what about cycles?
<TabAtkins> lea: it seems state-trigger can set a state, then you can select base don the state, how do we avoid a cycle?
<TabAtkins> ydaniv: currently i started very simple to see if there are blocks in the way,
<lea> Avoiding cycles was the motivation for the design in #12502 btw, otherwise this is much more elegant
<lea> Sorry, https://github.com//issues/12502
<TabAtkins> ydaniv: to answer Rob, today it can even be a one-liner to hook up classes or data attributes in response to events. so it's easy today, but this is more declarative and easier
<TabAtkins> flackr: specifically waht i meant is, it's already easy to make a declarative animation trigger that applies a state when the naimation trigger happens.
<lea> q+
<TabAtkins> flackr: so they won't need to use JS anyway once we ship that. so the q is how much this is needed if we can just change styles with an animation
<TabAtkins> ydaniv: there are cases where you just want to change styles, not run an animation. entire animation api is sometimes a bit much
<TabAtkins> ydaniv: another use-case for the future is to have this as a declarative mechanism for trigger scoped view-transitions, maybe
<TabAtkins> kbabbitt: same question as Lea for cycles
<Rossen> ack kbabbitt
<TabAtkins> kbabbitt: there is some precedent for how we scope this in CQs to guard against that... maybe it won't solve the use-cases here
<fantasai> TabAtkins: I don't believe from this presentation that there's potential for cycles, but confusing from presentation
<Rossen> ack TabAtkins
<fantasai> TabAtkins: This isn't a property like animation-trigger that defines stuff for other things to rely on.
<fantasai> TabAtkins: This is just, "when some other trigger occurs, then we can adjust states on the element". Doesn't respond to a state changing.
<fantasai> TabAtkins: The property is not named correctly for that.
<fantasai> TabAtkins: It doesn't define a trigger. It defines a response, like animation-trigger listens for triggers.
<fantasai> TabAtkins: It's like animation-trigger, not the trigger-defining properties.
<castastrophe> q+
<fantasai> ydaniv: Exactly, state-trigger property is analogous to animation-trigger
<fantasai> ydaniv: i.e. where you *reference* the trigger
<fantasai> ydaniv: and define the reaction to it
<Rossen> ack lea
<fantasai> lea: Does this affect :state() ?
<fantasai> TabAtkins: Yes, it does, but it's not cyclic in the same way that timeline-triggers are not cyclic
<fantasai> TabAtkins: What do you think is cyclic about this? What's the scenario that would cycle?
<fantasai> Lea: Thought you could set state foo via selector, and then use that to remove it
<fantasai> TabAtkins: It's not defining a trigger. It's responding to a trigger that has been defined.
<fantasai> TabAtkins: When an existing trigger source happens. Currently you can run an animation in response to that.
<fantasai> TabAtkins: This would allow us to also adjust the state-set.
<fantasai> TabAtkins: It is not causing an event trigger, it is saying how do I respond to a timeline or event trigger.
<fantasai> TabAtkins: Several people confused, so wanted to clarify!
<ydaniv> thanks TabAtkins!
<TabAtkins> fantasai: this seems cool, but also i'm not sure CSS changing the state is at the right level of abstraction
<TabAtkins> fantasai: there was a concern about authors being able to modify the state set in a way that CE devs aren't expecting
<Zakim> fantasai, you wanted to raise https://github.com/whatwg/html/issues/11466#issuecomment-3386922777
<fantasai> https://github.com/whatwg/html/issues/11466#issuecomment-3386922777
<TabAtkins> fantasai: this was raised on previous proposal, think it still applies
<Rossen> ack castastrophe
<TabAtkins> castastrophe: I think there needs to be more use-cases described for this, but i'm intrigued from design system perspective
<TabAtkins> castastrophe: many times we were building component UI, wanted to assign state that doesn't exist in HTML in styles, but didn't want to to be responsible for the JS
<ydaniv> q+
<TabAtkins> castastrophe: so don't necessarily want to manage a bunch of classes, just want a view component to trigger that state
<TabAtkins> castastrophe: so i think this is very clean for design systems, engineers never want to add a million state-based classes but i do want to acknowledge there is state
<TabAtkins> castastrophe: but i do think we need more use-cases, yeah
<TabAtkins> castastrophe: figure out where JS plays into it
<Rossen> ack ydaniv
<TabAtkins> ydaniv: def agree with Cass
<TabAtkins> ydaniv: we've had a lot of these features built for a long time, rolling it out now packaged as design system states
<TabAtkins> ydaniv: so this is based on existing design system use-cases, just declarative way to avoid having to maintain state separately or with JS
<TabAtkins> fantasai: so i think i understood from the discussion...
<TabAtkins> fantasai: there was a concern aobut cyclic, appears there sin't
<TabAtkins> fantasai: concern about CEs ability to reason about themselves, since this is coming from a different source
<hoch> q+
<TabAtkins> fantasai: and the ability to have a declarative way to manage state you can select off of is useful
<Rossen> ack hoch
<TabAtkins> hoch: one q abuot conflict resolution
<TabAtkins> hoch: can have multiple triggers, would be good to clarify the behavior if the same trigger says to add and remove a state, etc
<arronei> q+
<Rossen> ack arronei
<TabAtkins> arronei: a little concerned about the bikeshedding that may need to happen to clarify these names to amke sure people udnerstand this *isn't* cyclic
<TabAtkins> (agree, the use of *-trigger for both sides fo the equation is kinda bad actually)
<TabAtkins> arronei: so might be good to bikeshed the names)
<fantasai> TabAtkins: How locked-in are we on the name 'animation-trigger'?
<fantasai> TabAtkins: it's confusing that it's the opposite side of 'event-trigger' and 'timeline-trigger'
<fantasai> TabAtkins: The more we do stuff in this space the more confusing it's going to be
<fantasai> TabAtkins: We should come up with a better naming system
<arronei> random bikeshedding, *-hook, *-link, *-use, .....
<fantasai> TabAtkins: that makes it clearer whether we are defining or using the trigger
<astearns> *-trigger-response
<TabAtkins> Rossen: so there's clearly some interest in this
<TabAtkins> Rossen: and everything is bikesheddable, so that's ncie
<fantasai> I wonder if just swapping between trigger- and -trigger would help?
<TabAtkins> Rossen: how do we want to take this forward?
<kbabbitt> triggers-animation / triggers-state-change ?
<fantasai> ydaniv: good feedback. I was more concerned wrt a11y stuff, but nothing concrete yet
<TabAtkins> ydaniv: i guess we can continue on the issue
<TabAtkins> (we really want animatino-trigger to live in the animation-* namespace if possible)
<fantasai> ydaniv, might be useful to reach out to the a11y group?

[kizu]

I wanted to mention something similar to what @flackr wrote: this looks pretty similar to the container queries, and potentially block-level conditions (now that we have if()), and might intersect with some of the discussions we had about allowing some of the at-rules to be used on the selector level.

It would be great to have a comparison with those proposals and techniques we have today (container style queries, conditions), and what the upsides/downsides/intersections with this proposal are.

[LeaVerou]

Related: #12502

[ydaniv]

@flackr :

I think you can set up generic state-like changes with animation triggers with something like this:

@keyframes state-foo { to {--state: foo;} }
.target {
  animation: state-foo forwards;
  animation-trigger: --in-view;
  timeline-trigger: --in-view view();
  @container style(--state: foo) {
    /* Style descendants after state change */
  }
}

Yeah, for sure. That's what I mentioned that it's possible today, but it's hacky, and you need to target a container of the actual target. Also, the state management would also look cumbersome, unlike having add/remove/toggle-state() that is proposed.

@kizu:

Good point! That's an action item for improving the explainer.

@LeaVerou: of course 👍 , mentioned in the OP (: