# REALM

> REALM builds native web components with one HTML tag. A component is a <custom-element> holding a <script> (plain JavaScript with defineProps, useState and observe), a <style>, and markup that shows values with native <slot name="#state.path">, binds attributes with _attr="#ref", handles events with native on<event> attributes, repeats with <repeat-list> and fetches with attributes like fetch, into and render. No compiler and no build step.

Coding assistants can install the REALM agent skill with `npx skills add realmorg/realm`, or download it from http://realm.js.org/skills/realm.zip. See [Use REALM with coding assistants](http://realm.js.org/docs/ai-skill.md).

## Docs

- [Introduction](http://realm.js.org/docs.md): What REALM is, how a component is written, and the ideas behind it.
- [Installation](http://realm.js.org/docs/installation.md): Add REALM and REALM UI to an HTML page with tags from the jsDelivr CDN, pin exact versions for production, and host the files yourself.
- [Quick start](http://realm.js.org/docs/quick-start.md): Write your first REALM component in one HTML file, then move it into its own file and load it with import-element.
- [Tutorial: a reading list](http://realm.js.org/docs/tutorial.md): Build a small reading list app step by step, covering state, lists, events, derived values, conditional content, props, reactive CSS and persistence.
- [Component anatomy](http://realm.js.org/docs/components.md): How a custom-element definition is split into a script, styles and markup, how it is assembled without a compiler, and the rules that follow.
- [Props](http://realm.js.org/docs/props.md): Declare typed, validated attributes with defineProps and the prop builder, read them with @ references, and pass objects between components.
- [State and reactivity](http://realm.js.org/docs/state.md): Create reactive state with useState, derive values with getters, run side effects with observe, and wait for the DOM with tick.
- [Values and bindings](http://realm.js.org/docs/bindings.md): Show values with native slots, bind attributes and properties with the _ prefix, and understand references, negation, fallback content and how values are applied.
- [Events](http://realm.js.org/docs/events.md): Handle events with native on* attributes that call script functions, emit events with dispatchEvent or dispatch, handle custom events on pages, and expose methods with defineMethods.
- [Control flow](http://realm.js.org/docs/control-flow.md): Show and remove content with is-visible and is-hidden, compare values with eq, neq, gt, gte, lt, lte and contains, and hide without removing using _hidden.
- [Lists and keys](http://realm.js.org/docs/lists.md): Repeat content with repeat-list or the repeat attribute, and use keys so rows are moved instead of rebuilt.
- [Lifecycle](http://realm.js.org/docs/lifecycle.md): When a component's script runs, what happens when an element connects, moves or is removed, and what signal, host, refs and internals are.
- [Nested components and scope](http://realm.js.org/docs/scope.md): How references and handler names resolve across nested components, owner first and then parents, and when to pass data explicitly with props.
- [Fetching data](http://realm.js.org/docs/fetching.md): Make requests with attributes on the triggering element, load JSON into state, render server HTML, submit forms, and handle loadstart, load, error, abort, timeout and loadend.
- [Importing components](http://realm.js.org/docs/importing.md): Load component files with import-element, bundle many components in one file, lazy-load with loading=lazy and for, handle load and error, and import JavaScript modules from component scripts.
- [Stores](http://realm.js.org/docs/stores.md): Share app-wide state between components with defineStore, persist it to localStorage, sessionStorage or a custom adapter, and keep value types intact.
- [Styling](http://realm.js.org/docs/styling.md): Scoped shadow styles, :host and ::part, reactive CSS with --attr-* and --state-* variables and :state() selectors, design tokens, theming and dark mode.
- [Forms](http://realm.js.org/docs/forms.md): Build form-associated components that submit, reset, validate, disable and restore like native fields, with automatic value syncing and ref="control" delegation.
- [Accessibility](http://realm.js.org/docs/accessibility.md): Give components default roles, delegate focus, move focus with arrow keys using the focusgroup attribute, bind ARIA state, and label form fields.
- [Security](http://realm.js.org/docs/security.md): What REALM treats as code and what it treats as data, how inserted HTML is sanitised, and how to run REALM under a Content Security Policy with a nonce.
- [Performance and memory](http://realm.js.org/docs/performance.md): How REALM keeps updates small and stops listeners, timers, observers and requests when an element is removed.
- [Browser support](http://realm.js.org/docs/browser-support.md): Which browsers REALM supports, the platform features it relies on, and what is polyfilled or emulated.
- [Modern framework problems](http://realm.js.org/docs/framework-problems.md): A checklist of common front-end framework problems, such as FOUC, hydration, memory leaks, XSS, stale closures, fetch races, CSP and SEO, and how REALM handles each one, including its gaps.
- [Migrating from v1](http://realm.js.org/docs/migrating-from-v1.md): Move REALM v1 components to v2, with a cheat sheet that maps each v1 tag to its v2 replacement.
- [Use REALM with coding assistants](http://realm.js.org/docs/ai-skill.md): Install the REALM agent skill in Claude Code, Codex, Cursor and other assistants, or point them at llms.txt and the Markdown copy of every page.

## Reference

- [API reference](http://realm.js.org/reference.md): Index of every REALM element, attribute, script helper, event, CSS hook and JavaScript export.
- [References and durations](http://realm.js.org/reference/syntax.md): The reference syntax (#name.path, @prop, !) and duration syntax shared by every REALM attribute, and how names are resolved.
- [Console messages](http://realm.js.org/reference/console.md): Every warning and error REALM writes to the console, what causes it and what to do.
- [<custom-element>](http://realm.js.org/reference/elements/custom-element.md): The custom-element tag that defines a REALM component: its attributes, children, script types and instance behaviour.
- [<import-element>](http://realm.js.org/reference/elements/import-element.md): The import-element tag, which loads an HTML file of component definitions, with its attributes and events.
- [<repeat-list>](http://realm.js.org/reference/elements/repeat-list.md): The repeat-list tag, which repeats its content for each item of an array, with its attributes and keyed updates.
- [<is-visible>](http://realm.js.org/reference/elements/is-visible.md): The is-visible tag, which mounts its content while a reference is truthy or matches a comparison (eq, neq, gt, gte, lt, lte, contains).
- [<is-hidden>](http://realm.js.org/reference/elements/is-hidden.md): The is-hidden tag, which mounts its content while a reference is falsy or does not match a comparison.
- [Value slots](http://realm.js.org/reference/elements/value-slots.md): Slot elements whose name is a reference (#state.path or @prop), with text, html and html-unsafe modes, fallback content and SVG.
- [_ bindings](http://realm.js.org/reference/attributes/bindings.md): The _ prefix that binds an attribute, property or CSS custom property to a reference, and how each value type is applied.
- [on… handlers](http://realm.js.org/reference/attributes/handlers.md): on-event handler attributes in component markup and on plain pages, the names in scope, and return false.
- [debounce and throttle](http://realm.js.org/reference/attributes/debounce-throttle.md): The debounce and throttle attributes, which delay or rate-limit event handlers and requests.
- [ref](http://realm.js.org/reference/attributes/ref.md): The ref attribute, which names an element for refs, render targets and form control delegation.
- [repeat](http://realm.js.org/reference/attributes/repeat.md): The repeat attribute, which repeats an element once per array item inside lists, tables and selects.
- [focusgroup](http://realm.js.org/reference/attributes/focusgroup.md): The focusgroup attribute and its inline, block and wrap tokens for arrow-key, Home and End focus navigation.
- [fetch, method, params and headers](http://realm.js.org/reference/fetch/fetch.md): The fetch, method, params and headers attributes, which elements send requests, and what each request sends.
- [trigger and poll](http://realm.js.org/reference/fetch/trigger.md): The trigger and poll attributes, which decide when a fetch element sends its request.
- [into, into-mode and into-key](http://realm.js.org/reference/fetch/into.md): into, which writes a response into state, and into-mode and into-key for updating lists.
- [render, render-mode and render-select](http://realm.js.org/reference/fetch/render.md): render, which inserts a response as sanitised HTML into a ref, with render-mode and render-select.
- [busy and timeout](http://realm.js.org/reference/fetch/busy-timeout.md): busy, which writes whether a request is running into state, and timeout, which aborts slow requests.
- [Component script](http://realm.js.org/reference/script.md): How a REALM component script runs, which names it exposes to markup, the helpers in scope, imports, and the recommended order.
- [defineProps](http://realm.js.org/reference/script/define-props.md): Reference for defineProps, which declares a component's typed props, maps them to attributes and properties, validates them and returns a reactive object.
- [prop](http://realm.js.org/reference/script/prop.md): Reference for the prop type builder, every type (string, number, boolean, enum, date, array, object) and every rule (default, required, optional, reflect, attribute, min, max, int, pattern, email, url).
- [useState](http://realm.js.org/reference/script/use-state.md): Reference for useState, which returns a deep reactive proxy of a plain object or array, with getters as cached derived values and batched updates.
- [observe](http://realm.js.org/reference/script/observe.md): Reference for observe, which runs a function now and again whenever the reactive values it read change, with cleanup functions and automatic stop on removal.
- [tick](http://realm.js.org/reference/script/tick.md): Reference for tick, which resolves after pending reactive updates have been applied to the DOM.
- [defineStore](http://realm.js.org/reference/script/define-store.md): Reference for defineStore, which creates or returns an app-wide named reactive store, optionally persisted to localStorage, sessionStorage or a custom adapter.
- [host](http://realm.js.org/reference/script/host.md): Reference for host, the component element itself as seen from its script.
- [refs](http://realm.js.org/reference/script/refs.md): Reference for refs, the reactive object of elements named with the ref attribute in a component's markup.
- [signal](http://realm.js.org/reference/script/signal.md): Reference for signal, the AbortSignal that aborts when a component element is removed.
- [internals](http://realm.js.org/reference/script/internals.md): Reference for internals, the component's ElementInternals for custom states, ARIA and form association.
- [attrs](http://realm.js.org/reference/script/attrs.md): Reference for attrs, reactive read and write access to any attribute on the component host.
- [useChildren](http://realm.js.org/reference/script/use-children.md): Reference for useChildren, a reactive array of the host's direct light DOM children that match a selector.
- [defineMethods](http://realm.js.org/reference/script/define-methods.md): Reference for defineMethods, which exposes methods, getters and setters on the component element for outside code.
- [dispatch](http://realm.js.org/reference/script/dispatch.md): Reference for dispatch, which sends a bubbling, composed, cancelable CustomEvent from the component host.
- [listen](http://realm.js.org/reference/script/listen.md): Reference for listen, which adds an event listener on the host or another target that is removed with the element.
- [lookup](http://realm.js.org/reference/script/lookup.md): Reference for lookup, which reads a name from the nearest parent component that defines it, or from globalThis.
- [Timers](http://realm.js.org/reference/script/timers.md): Reference for the element-bound setTimeout, setInterval, clearTimeout and clearInterval available in component scripts, which stop when the element is removed.
- [onConnected](http://realm.js.org/reference/script/on-connected.md): Reference for onConnected, which runs a function once a component's markup is connected and refs are filled, with an optional cleanup.
- [onDisconnected](http://realm.js.org/reference/script/on-disconnected.md): Reference for onDisconnected, which runs a function when a component element is removed from the document.
- [onFormReset](http://realm.js.org/reference/script/on-form-reset.md): Reference for onFormReset, which runs when the form that owns a form-associated component is reset.
- [onFormDisabled](http://realm.js.org/reference/script/on-form-disabled.md): Reference for onFormDisabled, which runs when a form-associated component is disabled or enabled through its own attribute or a surrounding fieldset.
- [onFormStateRestore](http://realm.js.org/reference/script/on-form-state-restore.md): Reference for onFormStateRestore, which runs when the browser restores a form-associated component's value after navigation or autofill.
- [Request events](http://realm.js.org/reference/events/request-events.md): The loadstart, load, error, abort, timeout and loadend events fired by elements with fetch attributes, with their detail objects.
- [Import events](http://realm.js.org/reference/events/import-events.md): The load and error events fired by import-element, with their detail objects.
- [Component events](http://realm.js.org/reference/events/component-events.md): Events your components send with dispatch, how to handle them in markup and on plain pages, and the change event of delegated form controls.
- [realm.css](http://realm.js.org/reference/css/realm-css.md): realm.css, the page stylesheet that hides definitions and undefined elements, and the base rules REALM adds to every component.
- [--attr-* and --state-*](http://realm.js.org/reference/css/variables.md): The reactive CSS custom properties --attr-name and --state-path that REALM sets on a component host from props, attributes and state.
- [:state()](http://realm.js.org/reference/css/states.md): The reactive custom states REALM sets on a component host: :state(attr-…), :state(state-…), their comparisons, :state(loading) and your own states.
- [Design tokens](http://realm.js.org/reference/css/design-tokens.md): The design tokens in the REALM UI theme.css, their values, and how dark mode switches them.
- [Entry points](http://realm.js.org/reference/javascript/entry-points.md): Reference for the REALM package files and module entry points (realm.js, index.js, compiler.js, realm.css) and every name they export.
- [start](http://realm.js.org/reference/javascript/start.md): Reference for start, which adopts REALM's page stylesheet, registers import-element, defines every inline custom-element and watches for new ones.
- [importDefinitions](http://realm.js.org/reference/javascript/import-definitions.md): Reference for importDefinitions, which loads an HTML file from JavaScript and defines every custom-element in it, sharing requests with import-element.
- [defineComponent](http://realm.js.org/reference/javascript/define-component.md): Reference for defineComponent, the low-level function that defines a component from a custom-element element you already have.
- [flush](http://realm.js.org/reference/javascript/flush.md): Reference for flush, which applies pending reactive updates synchronously.
- [toRaw](http://realm.js.org/reference/javascript/to-raw.md): Reference for toRaw, which returns the original object behind a reactive proxy.
- [untrack](http://realm.js.org/reference/javascript/untrack.md): Reference for untrack, which runs a function without subscribing the current observer to what it reads.
- [Compiler](http://realm.js.org/reference/javascript/compiler.md): Reference for @realmorg/realm/compiler, the build-time module that turns a custom-element definition into a setup module (compileDefinition) and tokenizes scripts.
- [Vite plugin](http://realm.js.org/reference/tooling/vite-plugin.md): Reference for @realmorg/vite-plugin, which pre-assembles REALM components at build time for a strict Content Security Policy, writes a custom-elements.json manifest and serves component files untransformed in dev.

## Components

- [Components](http://realm.js.org/components.md): About sixty accessible ui-* web components built with REALM, plus a theme of design tokens with dark mode.
- [Theming](http://realm.js.org/components/theming.md): Change the colours, radius and font of REALM UI with CSS custom properties, and build a theme for light and dark mode in the browser.
- [Button](http://realm.js.org/components/button.md): A form-associated button with variants and sizes that can submit or reset a form, open popovers and invoke commands on dialogs.
- [Button Group](http://realm.js.org/components/button-group.md): Joins adjacent buttons or toggles into one connected control, such as a toolbar or a split button.
- [Calendar](http://realm.js.org/components/calendar.md): A month grid date picker that submits an ISO date with its form, with min and max limits, locale formatting and keyboard navigation.
- [Checkbox](http://realm.js.org/components/checkbox.md): A form-associated checkbox with a built-in label, indeterminate state and native validation.
- [Combobox](http://realm.js.org/components/combobox.md): A searchable, form-associated select that filters native option children as you type and submits the chosen value.
- [Field](http://realm.js.org/components/field.md): Layout wrappers that pair a form control with its label, description and error message, and group related fields under a legend.
- [Input](http://realm.js.org/components/input.md): A form-associated single-line text input that wraps a native input, with native types, constraints and validation.
- [Input Group](http://realm.js.org/components/input-group.md): A form-associated text input with start and end addons inside one border, for prefixes, suffixes, icons and inline buttons.
- [Input OTP](http://realm.js.org/components/input-otp.md): A one-time code input with one box per character, paste support and a complete event, that submits the whole code with its form.
- [Label](http://realm.js.org/components/label.md): A text label that names a form control by id, focuses it on click and toggles checkboxes and switches.
- [Radio Group](http://realm.js.org/components/radio-group.md): A form-associated set of radio buttons built from native option children, for choosing exactly one value.
- [Select](http://realm.js.org/components/select.md): A styled, form-associated native select that mirrors its option children, with an optional placeholder and validation.
- [Slider](http://realm.js.org/components/slider.md): A form-associated range slider built on a native range input, with a filled track and numeric value.
- [Switch](http://realm.js.org/components/switch.md): A form-associated on/off switch built on a native checkbox with the switch role, for settings that apply immediately.
- [Textarea](http://realm.js.org/components/textarea.md): A form-associated multi-line text field that wraps a native textarea and grows with its content.
- [Toggle](http://realm.js.org/components/toggle.md): A two-state button that stays pressed or unpressed, for options such as bold text or a pinned item.
- [Toggle Group](http://realm.js.org/components/toggle-group.md): A form-associated set of toggles where one or several can be pressed, submitting the pressed values as one field.
- [Alert](http://realm.js.org/components/alert.md): A callout box with an optional icon, a title and a description, for messages that need the reader's attention.
- [Avatar](http://realm.js.org/components/avatar.md): A round image of a user or entity, with a text fallback while the image loads or when it fails.
- [Badge](http://realm.js.org/components/badge.md): A small inline label for a status, a count or a category.
- [Card](http://realm.js.org/components/card.md): A bordered container with a header, body and footer for grouping related content and actions.
- [Chart](http://realm.js.org/components/chart.md): A small SVG bar, line or area chart drawn from a list of data objects, with one or more series.
- [Empty](http://realm.js.org/components/empty.md): A placeholder for an empty list, search result or section, with an icon, a message and actions.
- [Item](http://realm.js.org/components/item.md): A row with media, a title, a description and actions, for lists of people, files, settings or notifications.
- [Kbd](http://realm.js.org/components/kbd.md): Styled keyboard keys and key combinations for shortcuts in menus, buttons, tooltips and help text.
- [Progress](http://realm.js.org/components/progress.md): A horizontal bar showing how far a task has got, built on the native progress element.
- [Separator](http://realm.js.org/components/separator.md): A thin horizontal or vertical line that divides content, with the ARIA separator role.
- [Skeleton](http://realm.js.org/components/skeleton.md): A pulsing placeholder block that shows the shape of content while it loads.
- [Spinner](http://realm.js.org/components/spinner.md): A rotating loading indicator with the status role and an accessible label.
- [Table](http://realm.js.org/components/table.md): A data table rendered from a list of columns and rows, plus the pattern for building a custom table from component state.
- [Alert Dialog](http://realm.js.org/components/alert-dialog.md): A modal dialog with the alertdialog role that interrupts the user with a decision and only closes when an action is chosen.
- [Command](http://realm.js.org/components/command.md): A searchable list of commands with groups, shortcuts, an empty state and keyboard navigation, used inline or as a command palette inside a dialog.
- [Context Menu](http://realm.js.org/components/context-menu.md): A menu of actions that opens at the pointer when the user right-clicks an area, sharing its items with the dropdown menu.
- [Dialog](http://realm.js.org/components/dialog.md): A modal dialog built on the native dialog element, with a trigger, header, title, description, footer, close parts and optional side placement.
- [Drawer](http://realm.js.org/components/drawer.md): A modal panel that slides up from the bottom edge with a drag handle, or in from another edge, for mobile-friendly menus and forms.
- [Dropdown Menu](http://realm.js.org/components/dropdown-menu.md): A menu of actions that opens from a trigger, with labels, groups, separators, shortcuts, checkbox and radio items, keyboard navigation and a select event.
- [Hover Card](http://realm.js.org/components/hover-card.md): A card that previews the content behind a link when the pointer rests on it or it receives keyboard focus.
- [Popover](http://realm.js.org/components/popover.md): Floating content anchored to a trigger, built on the native popover attribute with light dismiss and placement.
- [Sheet](http://realm.js.org/components/sheet.md): A modal panel that slides in from an edge of the screen, for navigation, filters or secondary forms.
- [Toaster](http://realm.js.org/components/toaster.md): A live region that shows short, auto-dismissing notifications triggered by a document event or a method call.
- [Tooltip](http://realm.js.org/components/tooltip.md): A short text label that appears next to an element on hover or keyboard focus, built on a manual popover with anchor positioning.
- [Accordion](http://realm.js.org/components/accordion.md): A vertically stacked set of collapsible sections built on native details and summary, with one or several sections open at a time.
- [Breadcrumb](http://realm.js.org/components/breadcrumb.md): A trail of links showing where the current page sits in the site hierarchy.
- [Collapsible](http://realm.js.org/components/collapsible.md): A single section that shows and hides its content when its trigger is activated, built on native details and summary.
- [Menubar](http://realm.js.org/components/menubar.md): A horizontal bar of menus, like the File and Edit menus of a desktop application, with triggers, menus and shared menu items.
- [Navigation Menu](http://realm.js.org/components/navigation-menu.md): A site navigation bar of links and triggers that open popover panels of further links on hover or click.
- [Pagination](http://realm.js.org/components/pagination.md): Page navigation with previous and next controls, numbered pages and ellipses, driven by a page number and a page count.
- [Sidebar](http://realm.js.org/components/sidebar.md): An application shell with a collapsible side navigation, grouped menus, a toggle button, a keyboard shortcut and an off-canvas mode on small screens.
- [Tabs](http://realm.js.org/components/tabs.md): A set of panels shown one at a time, switched with a row or column of tab buttons.
- [Aspect Ratio](http://realm.js.org/components/aspect-ratio.md): A box that keeps its content at a fixed width-to-height ratio, for images, video and embeds.
- [Carousel](http://realm.js.org/components/carousel.md): A scroll-snapping slideshow with previous and next buttons, arrow-key navigation and swipe support.
- [Direction](http://realm.js.org/components/direction.md): A wrapper that sets left-to-right or right-to-left text direction for everything inside it.
- [Resizable](http://realm.js.org/components/resizable.md): Panel groups split by draggable handles that users resize with the pointer or the arrow keys.
- [Scroll Area](http://realm.js.org/components/scroll-area.md): A box with its own thin, themed scrollbar for content that is taller or wider than the space it is given.
- [Attachment](http://realm.js.org/components/attachment.md): A compact file chip with a preview area, a downloadable file name, its size and optional actions.
- [Bubble](http://realm.js.org/components/bubble.md): A rounded chat bubble for message text, with colour variants, start or end alignment and a reactions row.
- [Code Block](http://realm.js.org/components/code-block.md): A monospaced block for code with a language label and a copy-to-clipboard button.
- [Marker](http://realm.js.org/components/marker.md): A small muted line of text with an optional icon, for day separators, system notices and section labels in a conversation.
- [Message](http://realm.js.org/components/message.md): A chat message row that lays out an avatar, header, content and footer, aligned to the start or end.
- [Message Scroller](http://realm.js.org/components/message-scroller.md): A scrolling chat log that sticks to the newest message and offers a jump-to-latest button when the user scrolls up.

## Examples

- [Examples](http://realm.js.org/examples.md): Apps and page blocks built with REALM and REALM UI, including a todo list, kanban board, chess, a dashboard, a weather app, a contacts manager, a chat, a shop, notes, an expense tracker, a GitHub explorer, Minesweeper and sign-in forms.

## Blog

- [Blog](http://realm.js.org/blog.md): News and release notes from the REALM project.
- [REALM is dead, long live REALM](http://realm.js.org/blog/realm-v2.md): Why REALM v1 stopped, what changed in the REALM v2 rewrite, and how to start with it.
- [Project is under maintenance mode](http://realm.js.org/blog/project-is-under-maintenance-mode.md): Realm Framework has entered maintenance mode. This decision is due to instability in the Shadow DOM and Web Component API, ecosystem shifts, and diminished active usage.
- [Introducing Unicons by Realm](http://realm.js.org/blog/universal-web-component-icons.md): Universal Web Component Icons (Unicons) is a collection of icons ported from React Icons to be used as web components. It's designed to be used accross the web, so you can use icons from any website not limited to framework or library.
- [Initial Release 🎉](http://realm.js.org/blog/initial-release.md): Introducing Realm, a new way to build web application. HTML Framework for building MVP.