State API

§The contract

Each component instance binds a tiny API directly on the element. State lives on the element (never in module scope), so twenty components on one page can each hold a different state:

// the element - df$ selects it (get(0) = the node itself)

const el = df$('#confirm').get(0);

// set a declared state by name - throws on unknown names

el.api.setState('open', { /* optional config */ });

// read it back - always reflects the real UI

el.api.getState(); // → { name: 'open', config: { ... } }

Three guarantees, verified by the build's verifier for every component:

§Try it

The buttons below call api.setState() and print what api.getState() reads back. Closing the dialog with Escape or the backdrop flips the observed state to default on its own - the read always matches the UI.

§Discovering the states

Three places name the same list. The skill frontmatter is the machine-readable source - dist/SKILL.md indexes it, and every component's doc page shows the states with a live demo:

---

name: Dialog

type: MOL

...

supportedStates: default, open

---

## States

- `default` - closed (authored initial state)

- `open` - shown modally via showModal()

```js

df$('#confirm').get(0).api.setState('open');

```

The component scripts also register their states and a registry-level API on globalThis.df$ - useful when you have no element handle yet:

df$.shadcn.dialogStates;  // ['default', 'open']

// registry form - element passed explicitly, same contract as el.api

const { dialogApi } = df$.shadcn;

const confirm = df$('#confirm').get(0);

dialogApi.setState(confirm, 'open');

dialogApi.getState(confirm);

// → { name: 'open', config: {} }

§States across components

Every multi-state component, with its declared state names (from each skill's supportedStates). Components with no .js file are pure HTML/CSS - their only state is default, and their variants are markup attributes (Data Attribute API), not runtime states.

§Why it exists

The VAE page describes the proof loop: every declared state of every component must be visually verifiable - a screenshot per state per color scheme, driven through api.setState() by scripts/create-screenshots.ts - and asserted by an e2e test. That is only possible because the states are named, uniform, and callable from plain JavaScript, no matter what the component does internally. Your agents get the same handle: the skills name the states, the API drives them.

See also: How to Use (where the .js layer sits), Data Attribute API (markup configuration, as opposed to runtime state).

Comments, ideas or improvements? Edit this page's source on GitHub