# Documentation for AI agents This file is generated at build time from the Markdown documentation. Use it to choose the most relevant page before reading the canonical HTML documentation. ## WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/ Source: docs/index.md Description: Build reactive Web Components enhanced with state, props, scoped styles, lifecycles, and form integration — powered by Markup. ::: layout landing-hero version="@beforesemicolon/web-component" title="Web Components." title2="Now Reactive." primaryLabel="Get Started" secondaryLabel="npm i @beforesemicolon/web-component" === copy A tiny reactive layer over the native Web Components API. Props, state, scoped styles, and lifecycles — all buil ## What is WebComponent? - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/ Source: docs/documentation/index.md Description: WebComponent is a reactive layer on top of native Web Components API, powered by Markup. It adds state, props, scoped styles, and lifecycles. What is WebComponent? @beforesemicolon/web-component is a lightweight, compiler-free reactive layer built on top of the native Web Components API. It is powered by the @beforesemicolon/markup template engine to bring reactivity, state management, and scoped styling to standard Custom Elements. By design, the native Web ## Get Started - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/get-started Source: docs/documentation/get-started.md Description: Learn how to build your first reactive Web Component using the WebComponent class. Get Started This tutorial will guide you step-by-step through creating, registering, templating, and using your first reactive custom element using @beforesemicolon/web-component. Step 1: Declaring the Component Class To create a new component, declare a class that extends WebComponent. Step 2: Defining the Custom Elem ## Installation - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/installation Source: docs/documentation/installation.md Description: Install WebComponent via npm, yarn, pnpm or include it via CDN. Installation @beforesemicolon/web-component is a plug-and-play library. It does not require complex build steps, compiler configuration, or bundlers. You can use it by installing it via a package manager or directly including it from a CDN in a standard browser script tag. Via Package Managers Install the package using ## WebComponent Guide and Best Practices - Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/guide Source: docs/documentation/guide.md Description: Practical conventions for building reactive custom elements with @beforesemicolon/web-component. Guide & Best Practices Use @beforesemicolon/web-component when you want native custom elements with a small reactive layer for templates, props, state, scoped styles, lifecycle hooks, and form integration. Core Rules 1. Keep render() declarative: Return html, a Node, a string, or nothing. Do not start timers, fetch dat ## AI Guide - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/ai Source: docs/documentation/ai.md Description: AI-first guide to @beforesemicolon/web-component APIs, source boundaries, and common implementation mistakes. AI Guide Use this page first if you are an AI agent scanning the WebComponent docs. Read First - What is WebComponent? - Get Started - Guide & Best Practices - Creating Components - Props - State - Stylesheet - Events Package Boundary - @beforesemicolon/web-component exports WebComponent, HTMLComponentElement, css, and ## Creating Components - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/fundamentals/creating-components Source: docs/documentation/fundamentals/creating-components.md Description: Learn how to subclass WebComponent and register your custom elements. Creating Components To create a new custom element with @beforesemicolon/web-component, you subclass the WebComponent base class and register it with the browser using customElements.define(). Here is a basic example of a component: Tag Naming Requirements Custom element tag names must adhere to the standard HTML speci ## Rendering - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/fundamentals/rendering Source: docs/documentation/fundamentals/rendering.md Description: Learn about the render() method and how content slots work. Rendering The primary way to define a component's visual interface is by implementing the render() method. This method is called once during the component's initialization. The returned content is rendered into the component's contentRoot (which is either the shadow root or the element itself if shadow DOM is disabled) ## Config - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/fundamentals/config Source: docs/documentation/fundamentals/config.md Description: Configure Shadow DOM shadow root options on your components. Config By default, @beforesemicolon/web-component creates an encapsulated Shadow DOM for each component. You can customize the Shadow DOM configuration or completely opt out of it using the config class property. Default Configuration If you do not define a custom config property, the component defaults to the followin ## TypeScript - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/fundamentals/typescript Source: docs/documentation/fundamentals/typescript.md Description: Complete type safety and generics integration in WebComponent. TypeScript @beforesemicolon/web-component is designed with first-class TypeScript support, offering complete type safety for properties, internal state, reference bindings, and custom element interfaces. Subclassing with Generics The WebComponent base class accepts two optional generic parameters: Props and State. Cust ## Props - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/props-and-state/props Source: docs/documentation/props-and-state/props.md Description: Define and read reactive external properties mapped to observed attributes. Props Props are the external inputs to your component. In WebComponent, props are bound to HTML attributes, providing a reactive and seamless way to receive data from parents or external consumers. Declaring Props To declare reactive props, add their attribute names to the static observedAttributes array. WebComponent ## State - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/props-and-state/state Source: docs/documentation/props-and-state/state.md Description: Manage reactive local component state using initialState and setState. State State is the internal reactive data owned and managed exclusively by the component. Unlike props, state is not exposed or mapped to HTML attributes, and it is intended to store data that changes over the lifecycle of the component (e.g., UI toggle status, input values, API fetch results). Declaring Initial State ## Refs - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/props-and-state/refs Source: docs/documentation/props-and-state/refs.md Description: Safely reference and interact with rendered DOM elements inside your templates. Refs While declarative programming is preferred, there are times when you need to access DOM elements directly to perform imperative operations (e.g., focusing an input, playing a video, initializing third-party libraries, or measuring element dimensions). WebComponent integrates Markup's ref system to let you referenc ## Stylesheet - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/styling/stylesheet Source: docs/documentation/styling/stylesheet.md Description: Learn how to load, assign, and manage component styles using the stylesheet property. Stylesheet The stylesheet class property is the primary way to define styling for your component. WebComponent accepts a variety of stylesheet formats and processes them automatically based on your Shadow DOM configurations. Supported Stylesheet Formats You can assign a CSS string, a native CSSStyleSheet instance, or a ## css Utility - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/styling/css-utility Source: docs/documentation/styling/css-utility.md Description: Use the css tagged template literal to build highly reactive and dynamic component styles. css Utility For stylesheets that need to change dynamically in response to state or property updates, WebComponent provides the css tagged template literal. This utility lets you inject reactive functions and Markup helpers directly into your CSS code. How it Works The css tag returns an instance of the CSSStyle class. ## updateStylesheet - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/styling/update-stylesheet Source: docs/documentation/styling/update-stylesheet.md Description: Swap stylesheets dynamically at runtime using updateStylesheet. updateStylesheet While the css tagged template is perfect for fine-grained style changes, there are times when you need to replace or detach stylesheets entirely (e.g., swapping global themes, switching between light and dark mode stylesheets, or handling third-party stylesheets). You can perform these dynamic updates ## Events - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/events-and-lifecycle/events Source: docs/documentation/events-and-lifecycle/events.md Description: Learn how to dispatch and listen to custom events in WebComponent using the dispatch method. Events Custom elements often need to communicate changes or actions back to their parents or the rest of the application. @beforesemicolon/web-component provides a built-in helper method, this.dispatch(), to dispatch custom DOM events cleanly. Dispatching Custom Events To dispatch a custom event from inside a component ## Lifecycle - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/events-and-lifecycle/lifecycle Source: docs/documentation/events-and-lifecycle/lifecycle.md Description: Learn how to hook into key execution stages of your WebComponent using onMount, onDestroy, onUpdate, onAdoption, onError, and Markup effects. Lifecycle Every @beforesemicolon/web-component instance transitions through a series of lifecycle phases, starting from its construction to its destruction and removal from the DOM. Instead of dealing with native custom element callback names, @beforesemicolon/web-component provides clean, high-level hooks to handle se ## Error Handling - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/events-and-lifecycle/error-handling Source: docs/documentation/events-and-lifecycle/error-handling.md Description: Intercept and process runtime errors from render, state updates, styles, or lifecycles using the onError hook. Error Handling Handling runtime errors gracefully is crucial for building robust web applications. @beforesemicolon/web-component features a centralized onError() hook that allows you to intercept and handle errors occurring within the component boundary. The onError Hook By default, the onError hook logs the error to ## Form Integration - WebComponent by Before Semicolon URL: https://web-component.beforesemicolon.com/documentation/advanced/form-integration Source: docs/documentation/advanced/form-integration.md Description: Build form-associated custom elements with ElementInternals, submitted values, validation, disabled state, reset, and state restoration. Form Integration Custom elements can render inside a