custom-elements

Create a PascalCase folder pairing Component.astro with ComponentElement.ts. The .astro file renders markup with a kebab-case tag and data-* hooks, and its script only imports the element module; the element extends HTMLElement and wires listeners in connectedCallback.

Declare state as private #field class fields initialized in connectedCallback from typed querySelector calls against data-* attributes. Never query the DOM in the constructor, since it runs before the DOM exists.

After a ClientRouter swap, upgrades run ancestors first, so the descendant is still a plain HTMLElement when the parent's connectedCallback runs. Use queryUpgraded or queryAllUpgraded from the query-upgraded helper, or look the element up lazily at call time.

No. Public pages use only vanilla custom elements; React exists solely inside the Sanity Studio. The pattern replaces useState with private #fields, props with data-* attributes, and useEffect cleanup with connectedCallback and disconnectedCallback.

Define event handlers as arrow-function class fields so addEventListener and removeEventListener share one reference, then remove every listener in disconnectedCallback. Also abort in-flight fetches and destroy observers or animations there.

Always. Server-render the complete DOM and let the element only show, hide, fetch, or sync state, so pages work without JavaScript. Filtering toggles the hidden property on server-rendered nodes rather than rebuilding the list.