# Concorde by Supersoniks

> Concorde is the Supersoniks Lit web-components library (UI, DataProvider, decorators, forms, SDUI).
> npm: `@supersoniks/concorde` — https://www.npmjs.com/package/@supersoniks/concorde
> Site: https://concorde.supersoniks.org/

## Developer resources

- [Homepage (HTML)](https://concorde.supersoniks.org/) — interactive docs SPA
- [Homepage (Markdown)](https://concorde.supersoniks.org/index.md) — also via `Accept: text/markdown` on https://concorde.supersoniks.org/
- [llms-full.txt](https://concorde.supersoniks.org/llms-full.txt) — full plain-text mirror
- [Docs index](https://concorde.supersoniks.org/docs/index.html)
- [Sitemap](https://concorde.supersoniks.org/sitemap.xml)
- [npm package @supersoniks/concorde](https://www.npmjs.com/package/@supersoniks/concorde)
- [Getting started](https://concorde.supersoniks.org/docs/getting-started/start)
- [AI agents (skill)](https://concorde.supersoniks.org/docs/getting-started/ai-agents)
- [Components index](https://concorde.supersoniks.org/docs/getting-started/components)
- [custom-elements.json](https://concorde.supersoniks.org/custom-elements.json) — Custom Elements Manifest: attributes, properties, events and slots of every `sonic-*` element
- [About](https://concorde.supersoniks.org/about) · [Privacy](https://concorde.supersoniks.org/privacy)

Doc pages use the same pathnames as the interactive site (`/docs/…`, `/core/…`).
Markdown: same URL with `.md` (e.g. `/docs/getting-started/start.md`), or `Accept: text/markdown` on the pathname.
HTML crawlers receive a static HTML variant of the same URL.

## Topic hubs (start here for RAG)

- [Concorde decorators reference](https://concorde.supersoniks.org/hubs/decorators.html) (hubs/decorators, 12 pages)
- [Fetching remote data in Concorde](https://concorde.supersoniks.org/hubs/remote-data.html) (hubs/remote-data, 11 pages)
- [Concorde form components](https://concorde.supersoniks.org/hubs/form-components.html) (hubs/form-components, 9 pages)

## Docs

- [Date](https://concorde.supersoniks.org/core/components/functional/date) (core/components/functional/date/date): sonic-date formats a date or a date range with Intl.DateTimeFormat. Pass a Unix timestamp in seconds (date) or a parsable string (date_string), add end_date for a range, and tune each part (weekday · 
- [Fetch](https://concorde.supersoniks.org/core/components/functional/fetch) (core/components/functional/fetch/fetch): sonic-fetch sends a GET request to serviceURL + endPoint and publishes the response under dataProvider, so its children and any subscriber of that provider can render it. In a Lit component, prefer th
- [If](https://concorde.supersoniks.org/core/components/functional/if) (core/components/functional/if/if): sonic-if renders its default slot only while condition is true. Use it to show or hide a block from reactive state; with no condition, the content is not rendered. The host uses display: contents, so 
- [Jsonata](https://concorde.supersoniks.org/core/components/functional/jsonata) (core/components/functional/jsonata/jsonata): sonic-jsonata reads one data provider, evaluates a JSONata expression on it and writes the result to another data provider. Use it for read-only aggregates such as groups, rankings and totals; use Mix
- [List](https://concorde.supersoniks.org/core/components/functional/list) (core/components/functional/list/list): sonic-list renders one row per entry of its props array, either set directly or loaded with fetch. In TypeScript, prefer the .items row renderer (with .separator · .noItems · .skeleton); <template> ch
- [Mix](https://concorde.supersoniks.org/core/components/functional/mix) (core/components/functional/mix/mix): sonic-mix builds a new data provider from parts of other ones. Each key of composition maps to a source data provider id, with an optional dot path to a sub-value. The mixed provider is named by the d
- [Queue](https://concorde.supersoniks.org/core/components/functional/queue) (core/components/functional/queue/queue): sonic-queue loads a paginated API in batches and renders each batch as an internal List. Choose it over sonic-list for long or endless lists; the key attributes are dataProviderExpression · limit · da
- [Router](https://concorde.supersoniks.org/core/components/functional/router) (core/components/functional/router/router): sonic-router watches the location (pathname + hash) and renders the views whose route matches. From Lit, pass a .routes map of path patterns to render functions; use sonic-redirect to navigate when a 
- [SDUI — points d’extension publics](https://concorde.supersoniks.org/core/components/functional/sdui/sdui-extension-points) (core/components/functional/sdui/sdui-extension-points): Aide-mémoire pour les dépôts externes (adaptateurs, shells).
- [SDUI](https://concorde.supersoniks.org/core/components/functional/sdui) (core/components/functional/sdui/sdui): sonic-sdui builds an interface from a JSON descriptor (server-driven UI). Pass the descriptor through props, or add fetch and an endpoint to load it like Fetch. It renders in the light DOM with displa
- [States](https://concorde.supersoniks.org/core/components/functional/states) (core/components/functional/states/states): sonic-states renders the child <template> whose data-value matches a value of its data provider. Use it to switch views on a status or a selection; point data-path at the value, or set state directly.
- [Submit](https://concorde.supersoniks.org/core/components/functional/submit) (core/components/functional/submit/submit): sonic-submit sends the form publisher named by formDataProvider to a REST endpoint and writes the response to submitResultDataProvider. The request is configured like Fetch: serviceURL on an ancestor,
- [Subscriber](https://concorde.supersoniks.org/core/components/functional/subscriber) (core/components/functional/subscriber/subscriber): La mixin Subscriber permet lier un composant à un publisher.
- [Translation](https://concorde.supersoniks.org/core/components/functional/translation) (core/components/functional/translation/translation): sonic-t renders a translated label in plain HTML. It is the markup counterpart of the t() directive and shares its endpoint, batching and cache.
- [Value](https://concorde.supersoniks.org/core/components/functional/value) (core/components/functional/value/value): sonic-value prints one value from a data provider and updates when it changes. Set dataProvider (or inherit it from an ancestor) and point key at the field to show.
- [Alert messages](https://concorde.supersoniks.org/core/components/ui/alert-messages) (core/components/ui/alert-messages/alert-messages): sonic-alert-messages renders a vertical stack of sonic-alert items from a messages array on a linked data provider (typical pattern: submitResultDataProvider after a form submit). Only entries with ty
- [Alert](https://concorde.supersoniks.org/core/components/ui/alert) (core/components/ui/alert/alert): Alerts surface important feedback inline—errors, confirmations, or contextual help. Use label / text for simple copy, or the default slot for rich content (links, buttons). Set announce when the messa
- [Badge](https://concorde.supersoniks.org/core/components/ui/badge) (core/components/ui/badge/badge): Badges are compact, non-interactive labels for status, counts, or categories. They mirror sonic-button styling (type, variant, size) without focus rings or click handling—use a button when the control
- [Button](https://concorde.supersoniks.org/core/components/ui/button) (core/components/ui/button/button): sonic-button is the clickable control of the library: a plain button, a link when href is set, or a form toggle when it has a name and value. It shares type / variant / size with sonic-badge, and expo
- [Captcha](https://concorde.supersoniks.org/core/components/ui/captcha) (core/components/ui/captcha/captcha): sonic-captcha embeds an ALTCHA proof-of-work widget and makes the nearest form wait for it. Place it inside a form scope and put sonic-submit in its default slot: the widget renders above the slot con
- [Card](https://concorde.supersoniks.org/core/components/ui/card) (core/components/ui/card/card): Cards group related content on a padded surface with radius, theme type colors, and elevation. Default shadow is lg. Compose sonic-card-header / sonic-card-main / sonic-card-footer, or place any marku
- [Divider](https://concorde.supersoniks.org/core/components/ui/divider) (core/components/ui/divider/divider): sonic-divider draws a horizontal or vertical rule with optional centered label copy. Use it to separate sections in forms, cards, and sonic-menu. Set label for simple HTML captions or use the default 
- [Checkbox](https://concorde.supersoniks.org/core/components/ui/form/checkbox) (core/components/ui/form/checkbox/checkbox): sonic-checkbox is a styled checkbox that writes its value into form data. Give it a name and a formDataProvider (on the field or an ancestor); checkboxes sharing a name build an array of the checked v
- [Fieldset](https://concorde.supersoniks.org/core/components/ui/form/fieldset) (core/components/ui/form/fieldset/fieldset): sonic-fieldset groups related form controls in a bordered container rendered as a native <fieldset>. Put fields in the default slot and title the group with a slotted sonic-legend or with the label an
- [Form actions](https://concorde.supersoniks.org/core/components/ui/form/form-actions) (core/components/ui/form/form-actions/form-actions): sonic-form-actions lays out form footer controls (submit, cancel) in a wrapping flex row with a 0.3rem gap. Place it inside sonic-form-layout, where it spans the full width, or at the end of any block
- [Form layout](https://concorde.supersoniks.org/core/components/ui/form/form-layout) (core/components/ui/form/form-layout/form-layout): sonic-form-layout arranges slotted form controls in a responsive grid. Short fields (sonic-input · sonic-select) sit two per row when the host is wider than 440px; every other child spans the full wid
- [Input](https://concorde.supersoniks.org/core/components/ui/form/input) (core/components/ui/form/input/input): sonic-input wraps a native <input> with a label, a description, prefix and suffix slots and Concorde sizes. Native attributes (type, placeholder, pattern, min, max, …) are passed through. Bind the val
- [Radio](https://concorde.supersoniks.org/core/components/ui/form/radio) (core/components/ui/form/radio/radio): sonic-radio is a round Checkbox in radio mode: radios sharing a name under one formDataProvider store a single value, and a checked radio cannot be unchecked by a click. Label goes in the default slot
- [Select](https://concorde.supersoniks.org/core/components/ui/form/select) (core/components/ui/form/select/select): sonic-select wraps a native <select> with a label, a description, prefix and suffix slots and Concorde sizes. Options come from child <option> tags or from the options attribute (JSON). Bind the value
- [Switch](https://concorde.supersoniks.org/core/components/ui/form/switch) (core/components/ui/form/switch/switch): sonic-switch is a toggle-styled Checkbox in unique mode: when on, it stores its value under name in the formDataProvider data; when off, it stores null. Switches sharing a name behave as one choice, s
- [Textarea](https://concorde.supersoniks.org/core/components/ui/form/textarea) (core/components/ui/form/textarea/textarea): sonic-textarea wraps a native <textarea> with a label, a description and Concorde sizes. Native attributes (rows, cols, maxlength, wrap, …) are passed through. Bind the value to a store with formDataP
- [Group](https://concorde.supersoniks.org/core/components/ui/group) (core/components/ui/group/group): sonic-group lays out sonic-button · sonic-input and sonic-select controls in one row with a shared corner radius: only the outer corners of the first and last items stay rounded. Use it for button gro
- [Icon](https://concorde.supersoniks.org/core/components/ui/icon) (core/components/ui/icon/icon): sonic-icon renders inline SVG icons from the bundled core set or from CDN libraries. Set name (and library / prefix when needed); scale with size. Icons inherit currentColor and are aria-hidden by def
- [Image](https://concorde.supersoniks.org/core/components/ui/image) (core/components/ui/image/image): sonic-image wraps a responsive <img> with aspect ratio, object-fit: cover, optional rounded corners and a load transition. The host shows a placeholder background (--sc-placeholder-bg) until the file 
- [Link](https://concorde.supersoniks.org/core/components/ui/link) (core/components/ui/link/link): Links navigate with inherited typography: internal routes, anchors, or external URLs. The default slot is the anchor label. For in-app routing, pair href with pushstate; use autoActive to reflect the 
- [Loader](https://concorde.supersoniks.org/core/components/ui/loader) (core/components/ui/loader/loader): sonic-loader shows a loading animation, either in the content flow or as a viewport overlay. With no mode, it is fixed (centered overlay); use mode="inline" inside content areas. For Fetch and List, s
- [Menu](https://concorde.supersoniks.org/core/components/ui/menu) (core/components/ui/menu/menu): sonic-menu lays out navigation or actions as a direction row or column of sonic-menu-item entries (ghost variant and block shape by default), optional sonic-divider separators, and overflow content in
- [Modal](https://concorde.supersoniks.org/core/components/ui/modal) (core/components/ui/modal/modal): sonic-modal shows focused content in a dialog with a backdrop, an enter / exit animation and a built-in close button. Compose it with sonic-modal-title · sonic-modal-subtitle · sonic-modal-content · s
- [Pop](https://concorde.supersoniks.org/core/components/ui/pop) (core/components/ui/pop/pop): sonic-pop anchors a floating panel to a trigger: put the control in the default slot and the panel (menu, form, any markup) in slot="content". A click on the trigger toggles the panel unless manual is
- [Progress](https://concorde.supersoniks.org/core/components/ui/progress) (core/components/ui/progress/progress): Shows task completion on a value / max scale via a native <progress> bar. Omit value for an indeterminate loading animation. Put primary copy in the default slot and optional secondary text in remaini
- [Table](https://concorde.supersoniks.org/core/components/ui/table) (core/components/ui/table/table): sonic-table lays out tabular data with sonic-tr · sonic-th · sonic-td children, optionally grouped in sonic-thead · sonic-tbody · sonic-tfoot. It scrolls horizontally when columns overflow; set minWid
- [Theme](https://concorde.supersoniks.org/core/components/ui/theme) (core/components/ui/theme/theme): sonic-theme is the root element of a Concorde UI: it holds the --sc-* design tokens, optionally applies a built-in palette, and is where popovers, modals and toasts are mounted. Import @supersoniks/co
- [Toast](https://concorde.supersoniks.org/core/components/ui/toast) (core/components/ui/toast/toast): Toasts show short-lived feedback in a fixed stack at the bottom right of the page. Call SonicToast.add() (also window.SonicToast); the sonic-toast host is created on first use. Use label for a heading
- [Tooltip](https://concorde.supersoniks.org/core/components/ui/tooltip) (core/components/ui/tooltip/tooltip): sonic-tooltip shows a short label in a bubble when the trigger in the default slot is hovered or receives focus. With no placement, the bubble sits on top, centered. An empty label hides the bubble, l
- [@ancestorAttribute](https://concorde.supersoniks.org/docs/decorators/ancestor-attribute) (docs/decorators/ancestor-attribute): Copies the value of an attribute from the nearest element that carries it (the host itself, then its ancestors, across shadow roots) into a class property. Use it to pick up a scope such as dataProvid
- [@autoSubscribe](https://concorde.supersoniks.org/docs/decorators/auto-subscribe) (docs/decorators/auto-subscribe): Legacy decorator that re-runs a method whenever one of the store values it reads is assigned. For new code, prefer @subscribe with a DataProviderKey: dependencies are explicit and typed.
- [@bind](https://concorde.supersoniks.org/docs/decorators/bind) (docs/decorators/bind): @bind(key) keeps a class property and one path of the DataProvider store in sync. With { reflect: true } the sync goes both ways: the property follows the store, and each assignment is written back to
- [@get](https://concorde.supersoniks.org/docs/decorators/get) (docs/decorators/get): @get(endpoint) runs an HTTP GET on an Endpoint and stores the full ApiResult<T> in a property, or passes it to a method. It runs again when the endpoint's placeholders or the API configuration change,
- [@handle](https://concorde.supersoniks.org/docs/decorators/handle) (docs/decorators/handle): @handle(...keys) calls the decorated method each time a publisher assigns one of up to three store paths, with one typed argument per key. Nothing is stored on the component: use it for derived values
- [@onAssign](https://concorde.supersoniks.org/docs/decorators/on-assign) (docs/decorators/on-assign): Legacy decorator that calls a method with the values at one or more string paths of the store, once all of them are defined. For new code, use @handle with { waitForAllDefined: true }: same behaviour,
- [@patch](https://concorde.supersoniks.org/docs/decorators/patch) (docs/decorators/patch): Sends the value of a publisher as the body of a PATCH request, to update part of a resource, and stores the response in an ApiResult<T> property. It takes the same arguments, options and send(componen
- [@post](https://concorde.supersoniks.org/docs/decorators/post) (docs/decorators/post): Sends the value of a publisher as the body of a POST request and stores the response in an ApiResult<T> property. Pass an Endpoint and a DataProviderKey for the body; the request runs on connect and a
- [@publish](https://concorde.supersoniks.org/docs/decorators/publish) (docs/decorators/publish): @publish(key) writes a component property to one path of the store: every assignment to the property is published there. It never reads back from the store; it is the inverse of @subscribe. See Data f
- [@put](https://concorde.supersoniks.org/docs/decorators/put) (docs/decorators/put): Sends the value of a publisher as the body of a PUT request, to replace a resource, and stores the response in an ApiResult<T> property. It takes the same arguments, options and send(component) handle
- [@subscribe](https://concorde.supersoniks.org/docs/decorators/subscribe) (docs/decorators/subscribe): @subscribe(key) keeps a component property in sync with one path of the store: when a publisher assigns that path, the property updates and the component re-renders. It is read-only; use @publish to w
- [@awaitConnectedAncestors](https://concorde.supersoniks.org/docs/decorators/wait-for-ancestors) (docs/decorators/wait-for-ancestors): Delays a component's connectedCallback until its matching ancestors are defined and connected, so context they set up (a dataProvider, a publisher, a fetched payload) is ready when the child starts. P
- [sub()](https://concorde.supersoniks.org/docs/directives/sub) (docs/directives/sub): sub(path) is a Lit directive that renders the current value of a store path and updates in place on every assignment. Use it inside html templates for read-only display; in a decorator, the same path 
- [t()](https://concorde.supersoniks.org/docs/directives/t) (docs/directives/t): Lit directive that renders a translated label by key. Keys are batched into one GET to the endpoint set by the nearest wordingProvider ancestor attribute, and results are cached in localStorage.
- [AI agents (skill)](https://concorde.supersoniks.org/docs/getting-started/ai-agents) (docs/getting-started/ai-agents): Concorde ships one Agent Skill, concorde, so coding agents follow the framework patterns. Cursor, Claude Code, JetBrains Junie and other agents load it on their own when they work on Concorde code; th
- [Components](https://concorde.supersoniks.org/docs/getting-started/components) (docs/getting-started/components): Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path.
- [Creating components](https://concorde.supersoniks.org/docs/getting-started/create-a-component) (docs/getting-started/create-a-component): > New app components: start with My first component and Data flow. The Subscriber mixin below is legacy.
- [Data flow](https://concorde.supersoniks.org/docs/getting-started/dataFlow) (docs/getting-started/dataFlow): Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a DataProvider store.
- [Installation](https://concorde.supersoniks.org/docs/getting-started/installation) (docs/getting-started/installation): Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.
- [My first component](https://concorde.supersoniks.org/docs/getting-started/my-first-component) (docs/getting-started/my-first-component): Build a Lit user card with Tailwind and Concorde UI, then connect it to the DataProvider store: declare the data configuration (type, key, scope), and let @subscribe keep the card in sync.
- [Introduction](https://concorde.supersoniks.org/docs/getting-started/start) (docs/getting-started/start): Based on lit.dev, Concorde is a collection of web components for shared apps and websites.
- [Theming](https://concorde.supersoniks.org/docs/getting-started/theming) (docs/getting-started/theming): Concorde components ship with default styles (fallback values in each component and in <sonic-theme>).
- [API configuration](https://concorde.supersoniks.org/docs/misc/api-configuration) (docs/misc/api-configuration): APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get / @post configuration key). It is passed to API by fetchers, 
- [DataProviderKey](https://concorde.supersoniks.org/docs/misc/dataProviderKey) (docs/misc/dataProviderKey): The DataProviderKey<T> utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via toString() or the
- [Local API demos (offline)](https://concorde.supersoniks.org/docs/misc/docs-mock-api) (docs/misc/docs-mock-api): The Concorde doc site does not call fragile third-party APIs during yarn dev. A Service Worker and the Vite dev middleware serve /docs-mock-api/* on the same origin.
- [Dynamic path placeholders](https://concorde.supersoniks.org/docs/misc/dynamic-path) (docs/misc/dynamic-path): Decorators and DataProviderKey paths can include placeholders resolved on the host component at runtime:
- [Endpoint](https://concorde.supersoniks.org/docs/misc/endpoint) (docs/misc/endpoint): Endpoint<T, U> describes a single HTTP path (or a path accepted by API.get) and carries the expected response type T. Unlike DataProviderKey, there is no dot-navigation: the path is one string.
- [HTML integration (no Lit)](https://concorde.supersoniks.org/docs/misc/html-integration) (docs/misc/html-integration): Some hosts (legacy PHP pages, static HTML) embed Concorde components without a Lit build step. They can use HTML attributes such as data-bind, dataProvider, and formDataProvider on tags directly in th

## Optional

- [Full index](https://concorde.supersoniks.org/docs/index.html)