Swell UI (@swell/swell-ui) is a library of web components for the UI of Swell apps: buttons, text fields, selects, radio groups, tabs, status messages and more. Swell's hosted checkout is built from them. Each host sets their look through design tokens, so UI built from them matches the page around it and follows its light or dark theme.

The components are custom elements, such as <swell-button> and <swell-input>, so they work in any framework or none. They look finished with no configuration.

Build the UI of an app's UI components and frontend from Swell UI's elements, and style only the markup it has no element for, with its CSS variables.

Set ui: true in the component's config. The platform loads Swell UI into the component's frame before the first render, configured like the host page, and applies the host's later changes:

import type { ComponentProps } from '@swell/apps-sdk/components';

export const config = {
  description: 'Gift message for the order',
  ui: true,
};

export default function GiftMessage({ value, setValue, readonly }: ComponentProps<string | null>) {
  return (
    <swell-textarea
      label="Gift message"
      value={value ?? ''}
      readonly={readonly}
      oninput={(event) => setValue(event.target.value || null)}
    />
  );
}

The platform supplies Swell UI's code, so a component uses the elements by their tags. When you push, the CLI leaves every value import of @swell/swell-ui out of the component's bundle and warns: "@swell/swell-ui" is left out of the bundle: set config.ui = true in the component and the platform loads the Swell UI kit; import the kit only as types. Its functions are on the global SwellUI instead, and its React wrappers aren't available in a component.

ui must be true or false. swell app push rejects any other value with ui must be true or false. A component without ui: true never loads Swell UI, and its frame has no styles of its own. UI components need Swell CLI 2.9.36 and @swell/apps-sdk 2.1.0 or later for Swell UI.

To type the elements, install the package as a dev dependency:

npm install -D @swell/swell-ui

Then add @swell/swell-ui, which declares the global SwellUI, and @swell/swell-ui/preact, which types the elements in Preact's JSX, to types in components/tsconfig.json. swell create component writes "types": []:

{
  "compilerOptions": {
    "types": ["@swell/swell-ui", "@swell/swell-ui/preact"]
  }
}

Event props are lowercase, as these types name them: oninput, onchange, ontoggle and onremove. event.target is the element.

The look of Swell UI in a component comes from the host. Hosted checkout passes its configuration, so a payment component takes the checkout's colors, font and corner radius. The Swell dashboard passes none, so a field component takes Swell UI's default look. In both, Swell UI follows the host's light or dark theme, so a component needs no theme CSS and no configure() call of its own. The ui prop holds { config }, the configuration the host passed.

When Swell UI can't load, the component still renders without it, and the frame reports the error to the host.

Install the package from npm, and import it once in code that runs in the browser. Its entry holds the configuration and the loader, which loads each element the first time its tag appears on the page:

npm install @swell/swell-ui
import { configure } from '@swell/swell-ui';

Without a bundler, load the copy that Swell serves at /.swell/ui/v1/index.js on every Swell domain, including an app's frontend domain and a store's storefront domains. It is a module script, and it sets the global SwellUI. v1 is the major version:

<script type="module" src="/.swell/ui/v1/index.js"></script>
<swell-text type="heading">Delivery</swell-text>

Swell UI runs in the browser only, and importing it on a server throws. A frontend that renders on the server imports it in the browser only. With the swell-vinext template, load a component built from Swell UI with dynamic(() => import('./GiftForm'), { ssr: false }) from next/dynamic, inside a "use client" component. The swell-react template renders in the browser and imports Swell UI directly.

No host passes a configuration to a frontend, so Swell UI draws its default look until the frontend calls configure() with its own values, such as a storefront's brand colors. See Configuration below.

Swell UI defines its global tokens as CSS variables on every page it loads in, named --swell- followed by the token's name with hyphens for dots. They carry the host's values and follow its theme, so markup of your own that reads them matches the components around it:

.gift-note {
  padding: 12px 16px;
  border: var(--swell-border-width) solid var(--swell-color-border);
  border-radius: var(--swell-border-radius);
  background: var(--swell-color-secondary-background);
  color: var(--swell-color-secondary-foreground);
  font-family: var(--swell-font-family);
}

Use the elements in plain markup, or in a framework's templates:

<swell-button>Continue</swell-button>
<swell-button variant="secondary">Edit</swell-button>
<swell-button variant="secondary" appearance="plain" size="small">Cancel</swell-button>

Fields such as <swell-input>, <swell-select> and <swell-radio> take part in the form around them as native fields do: they send their name and value with the form, and required stops the form from being sent while they're empty.

Swell UI has no icon set. Put your own icon in an element's start or end slot. An <svg> there takes the element's icon size and the current color, so draw it with currentColor:

<swell-input label="Address">
  <svg slot="start" viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">…</svg>
</swell-input>

Each element is a chunk of its own. A page downloads the entry, the configuration and the chunks of the elements it renders.

  • The loader watches the document: every Swell UI element on the page when the entry runs, and every one added later, loads its chunk once.
  • Until its chunk loads, an element is hidden and keeps its place in the layout.
  • A component that renders elements in a shadow root of its own passes the root to load, which watches it as it watches the document: SwellUI.load(this.shadowRoot).
  • load(tags) loads elements before they appear, and ready(tags) waits until they are defined. ready() waits for every Swell UI element on the page now. Both reject when a chunk can't load.
  • @swell/swell-ui/elements/<name> defines the element swell-<name> as soon as it is imported, and exports its class. Import the elements of a page's first screen this way and leave the rest to the loader.
  • In the copy Swell serves, a chunk that fails to load, such as one a deploy replaced while the page was open, makes the loader import a fresh entry once. An element that still doesn't load stays undefined and is reported with console.error, and the rest of the page keeps working.
import { load, ready } from '@swell/swell-ui';

load(['swell-button', 'swell-input']);
await ready();

The package carries types and editor data for the elements.

  • React 16.8 or later: use the typed wrappers from @swell/swell-ui/react, such as SwellButton and SwellQuantity, which set properties and listen to the elements' events. Each wrapper defines its element when it is imported. A handler gets the element as event.currentTarget. As on a native field, onInput fires on every change of a field's value and onChange once the user commits it.
  • Preact, Solid, Vue and Svelte: use the elements by their tags, and add @swell/swell-ui/preact, /solid, /vue or /svelte to compilerOptions.types in tsconfig.json to type every element's attributes, properties and events. Vue renders the elements as custom elements when its compiler option isCustomElement returns true for tags that start with swell-.
  • Editors: JetBrains IDEs read the package's web-types.json. In VS Code, add the package's custom data files to the workspace settings.
import { SwellQuantity } from '@swell/swell-ui/react';

<SwellQuantity aria-label="Quantity" value={count} onChange={(event) => setCount(event.currentTarget.value)} />;
{
  "html.customData": ["./node_modules/@swell/swell-ui/dist/editors/vscode.html-custom-data.json"],
  "css.customData": ["./node_modules/@swell/swell-ui/dist/editors/vscode.css-custom-data.json"]
}

Swell UI runs in Chrome 125, Firefox 126, Safari 17.5 and later. The elements rely on custom states (:state()), light-dark() colors, the Popover API, constructable stylesheets and ElementInternals.

A host configures Swell UI's look from JavaScript, at any time, with configure(). The elements on the page follow each call, before or after they render:

SwellUI.configure({
  color: {
    background: { light: '#ffffff', dark: '#14171d' },
    foreground: { light: '#0e1117', dark: '#e8eaef' },
    accent: { light: '#0a7c4a', dark: '#3ecf8e' },
  },
  font: { family: 'Inter', size: '15px' },
  control: { height: '40px' },
  field: { appearance: 'filled', label: { position: 'above' } },
  components: {
    button: {
      border: { radius: '12px' },
      secondary: { appearance: 'filled' },
    },
    text: { heading: { font: { size: '22px', weight: 700 } } },
  },
  theme: 'system',
});
  • The keys are the token names. A global token sits at its name, such as control.small.height at control: { small: { height } }, and a component's token under components, such as button.large.height at components: { button: { large: { height } } }. The type Config of @swell/swell-ui lists every key.
  • A color is one value for both themes, or { light, dark } with both. Every other token takes one value for both themes: a CSS string such as "40px", a number for font weights, or a name or list of names for font families.
  • Font families are names. The host loads the font files.
  • Each call replaces the page's configuration, the theme included. A token you leave out takes its default, and configure() with no configuration restores the defaults.
  • Unknown keys and invalid values are reported in the console and skipped.

The theme is light, dark or system, which follows the system setting. Set it with the theme key, or with setTheme(), which keeps the rest of the configuration. Without a theme, Swell UI follows the color-scheme of the page.

SwellUI.setTheme('dark');

An area of the page can take token values of its own, such as an order summary in a brand's colors. configure(config, id) registers the area's configuration, and <swell-ui config="id"> applies it to everything inside, your own markup included. Values the area leaves out come from the page:

SwellUI.configure({ theme: 'light', color: { background: '#e7d7bc', accent: '#17130e' } }, 'summary');
<swell-ui config="summary"><aside class="summary">…</aside></swell-ui>

An area's configuration holds tokens and theme. Settings apply to the whole page, so an area reports and skips them. A second call with the same id replaces the area's configuration, and configure(undefined, id) removes it.

  • getConfig() returns the applied configuration with the theme in effect, and getConfig(id) an area's own configuration.
  • onChange(listener) calls listener after every configure() and setTheme(), and returns a function that removes the listener.
  • version is the version of Swell UI on the page.
  • These functions, with load and ready, are exported from @swell/swell-ui and are also on the global SwellUI.

Tokens are the design values of the elements. Each token has a default, and Swell UI looks finished with none configured. Global tokens hold values that several elements share, in the groups color, font, border, focus, motion, control, field and overlay. Component tokens hold the values of one element each, such as button and radio.

The base values, the ones most sites change, are color.background, color.foreground, color.accent, color.danger, font.family, font.size, border.radius and control.height. A token whose default references another one follows it until you set its own value: changing color.accent also changes button.color.background and focus.color. Swell UI computes no color from another, so when you change color.background or color.foreground, also set the colors drawn from them, such as color.border and color.secondary.background.

Colors are named by role: background, foreground, border, accent (text, links, outlines and icons where there is no fill), ring and shadow. color.danger, color.success and color.warning color errors, successes and warnings.

In CSS, each token is a variable named --swell- followed by its name with hyphens for dots: color.secondary.background is --swell-color-secondary-background. Every token's default and description is in the package, in tokens/*.json and each element's tokens.json under src/components/core/, in the W3C Design Tokens format. TOKENS.md in the package describes each element's appearances in detail.

The variant attribute picks the palette of color an element takes its colors from. primary is an element without the attribute. secondary is a quieter palette, color.secondary. button, badge, link, text and thumbnail take variants.

To add a variant of your own, add a palette to color at its name, with background, foreground, border and accent, and optionally shadow. Elements take it with variant="<name>". The name is a lowercase word other than primary, the palette roles, variant, size, type and state.

SwellUI.configure({
  color: { promo: { background: '#fde68a', foreground: '#422006', border: '#f59e0b', accent: '#b45309' } },
});
<swell-button variant="promo">Claim offer</swell-button>

Settings hold the choices no token value expresses. Set them in the configuration at their names, such as field: { appearance: 'filled' } and components: { button: { secondary: { appearance: 'filled' } } }. An element's attribute overrides the setting on that element: appearance for button.appearance, and indicator-position on a radio group for radio.indicator.position.

SettingValuesDefault
button.appearancefilled, outline, plainfilled
button.secondary.appearancefilled, outline, plainoutline
status.appearancefilled, outline, plainfilled
badge.appearancefilled, outlineoutline
card.appearanceoutline, filledoutline
tabs.appearanceunderline, segmentedunderline
field.appearanceoutline, filled, underlineoutline
field.label.positionabove, floatingfloating
radio.appearanceplain, outlineplain
radio.indicator.positionstart, endstart

Some appearances come from the attribute only: segmented and button on a radio group, plain on a link, quiet on a status message, card on a skeleton and steps on tabs.

The size attribute is one of xsmall, small, medium, large and xlarge, and defaults to medium. Each size sets a height and a text size, in px, and every other measure of an element follows from them. Badges and chips have scales of their own. Every target stays at least 24px.

Tokensxsmallsmallmediumlargexlarge
control..height3240485664
control..font.size1213141618
badge..height1620242832
badge..font.size1011121314
chip..height2428323640
chip..font.size1112131416

The control scale applies to buttons, text fields, selects, lookups, quantities, segmented radio groups, thumbnails and tabs, and its text sizes to checkboxes, radio options, status messages and plain links. A field of size xsmall puts its label above the field.

Every element below is defined by the loader on first use. In React, each has a wrapper named after its tag in PascalCase, such as SwellButton for <swell-button>. Style an element's CSS parts with ::part(), and select its states with :state(), such as swell-button:state(outline).

Text: a title, a heading, a subheading, strong text, body text, a caption, a footnote or an eyebrow.

AttributeTypeDescription
levelnumberThe heading level, 1 to 6: it makes text of any type a heading. A title, a heading and a subheading are headings of level 1, 2 and 3 by default.
variantstringWhich palette of color the text takes its color from: secondary, quiet text, or a variant of the host's own; without it, the text color.
typetitle, heading, subheading, strong, body, caption, footnote, eyebrowWhat the text is; body text by default. An eyebrow is uppercase.
SlotDescription
(default)The text.

A card: a box that groups content, such as the details of an order or a note under a choice.

AttributeTypeDescription
appearanceoutline, filledHow the card is drawn: with a border, or filled with the quiet background; the configured setting by default.
sizexsmall, small, medium, large, xlargeHow large the padding is: it follows the text of the size; medium by default.
SlotDescription
(default)The content.
StateDescription
outlineThe card has a border.
filledThe card is filled.

A divider: a line across its width, or two lines with a label between them, such as "or pay another way". Without a label it is a separator for screen readers; with one, they read the label and skip the lines. The host sets the space around it.

SlotDescription
(default)An optional label, such as text or an icon, drawn in the caption font and the secondary text color; whitespace and hidden content aren't one.

A badge: a short label or a count, such as a subscription's interval, a discount or a quantity. It is text only: screen readers read it in place, so a count needs its context in the host's markup, such as hidden text next to it.

AttributeTypeDescription
variantstringWhich palette of color the badge takes its colors from: secondary, quiet, or a variant of the host's own; without it, the badge's own.
appearancefilled, outlineHow the badge is drawn; the configured setting by default.
sizexsmall, small, medium, large, xlargeHow large the badge is; medium by default. A small one fits a count, an extra small one a count on an icon.
SlotDescription
(default)The label.
startAn icon before the label, drawn 1px larger than the text.
StateDescription
filledThe badge is filled.
outlineThe badge has an outline.

A thumbnail: a picture, an icon or initials in a small box, such as the photo of a cart line or a person's avatar. It is decoration, hidden from screen readers, with its badge; with aria-label it is an image with that name, which then carries what the badge says, such as the quantity. aria-hidden="true" and role="img" count as the kit's; any other value is the host's and stays.

AttributeTypeDescription
aria-labelThe element's accessible name, when it has no visible label.
variantstringWhich palette of color the box takes its colors from: secondary, the quiet colors with a border, as for a product without a photo, or a variant of the host's own; without it, the accent, as for an avatar.
sizexsmall, small, medium, large, xlargeHow large the box is: the height of a control of the size; medium by default.
shapecircleRounds the box fully, as for an avatar.
SlotDescription
(default)An , which covers the box, an svg icon, or initials.
badgeA over the top end corner, such as the quantity of a cart line.

A skeleton: a shimmering bar that stands in for content while it loads, such as a delivery option's name and price. The host sets its width through style and marks the region it fills with aria-busy="true"; the skeleton itself is hidden from screen readers. Screen readers don't all announce aria-busy, so a host can also say what is loading in a polite message, such as a visually hidden <swell-status>.

AttributeTypeDescription
sizexsmall, small, medium, large, xlargeHow large the skeleton is: a bar is 4px lower than the text of the size, a card as high as a control; medium by default. The bars of a card keep their own size, so give them the card's.
appearancecardcard draws the empty frame of an option card with its bars at its ends; only the attribute sets it. Without it, the skeleton is a bar.
SlotDescription
(default)The bars of a card.
StateDescription
cardThe skeleton is the frame of an option card.

A status message: an error, a success or a warning. Screen readers announce it when it is added after the page has loaded and when its text or type changes: each message goes into a fresh visually hidden region, an alert for danger and a status otherwise.

AttributeTypeDescription
typedanger, success, warningWhat the message means: its color, icon and how it is announced.
sizexsmall, small, medium, large, xlargeHow large the message is: its text, padding and icon follow the text of the size; medium by default.
appearancefilled, outline, plain, quietHow the message is drawn; the configured setting by default. quiet, for a note, comes from the attribute only.
SlotDescription
(default)The message.
startAn icon before the message, drawn 4px larger than the text, or 2px larger than the smaller text of a plain message; it replaces the type's icon and is hidden from screen readers.
endAn action after the message, such as a ; it is left out of the announcement.
CSS partDescription
messageThe message box.
StateDescription
filledThe message has its background, border and icon.
outlineThe message has its border and icon.
plainThe message has its icon only and the font of a field error.
quietThe message is a note in the quiet palette, without a border or the type's icon.
end-contentThe message has content in its end slot: its items are centered.
typedThe message has a known type and isn't quiet: it takes the colors of its type.

A button. It submits or resets the form it belongs to, like a native button. With href it is a link that looks like the button: an anchor in its shadow root fills it inside the border, takes the focus and follows the link, named by the element's own aria-label, or else by its content; type, disabled, loading and success belong to the button without href. role="button" and tabindex="0" count as the kit's and leave when href comes; any other role or tabindex is the host's and stays.

While loading, the button shows a spinner in place of its start content, hides its end content and ignores clicks; it keeps its focus. With success, it is filled with the success color and shows a check in place of its icons and its spinner. It is inactive, as after a payment, but keeps its focus and doesn't fade.

AttributeTypeDescription
disabledbooleanRemoves the button from the tab order and ignores clicks.
loadingbooleanShows a spinner, marks the button busy and ignores clicks; the button stays in the tab order.
successbooleanFills the button with the success color, draws a check and makes the button inactive; it keeps its tab stop and isn't busy.
variantstringWhich palette of color the button takes its colors from: secondary, or a variant of the host's own; without it, the button's own.
appearancefilled, outline, plainHow the button is drawn; the variant's setting by default.
sizexsmall, small, medium, large, xlargeHow large the button is; medium by default. xsmall fits an action inside a status message.
shapepillRounds the corners fully, in every variant, appearance and size, whatever the corner radius of the host's buttons.
hrefstringWhere the button leads; with it the element is a link, named by its own aria-label, or else by its content.
targetstringWhere to open the link.
relstringHow the link's target relates to the page.
typesubmit, reset, buttonWhat the button does in a form; submit by default.

Properties and methods:

  • shake(): Shakes the button, as after a failed attempt to submit; each call starts the shake again.
  • focus(): Focuses the anchor with href, and the button itself without it.
SlotDescription
(default)The label of the button.
startAn icon before the label, drawn 4px larger than the text.
endAn icon after the label, drawn 4px larger than the text; it moves toward the end on hover.
StateDescription
filledThe button is filled.
outlineThe button has an outline.
plainThe button has neither a fill nor a border at rest; under the pointer it takes the quiet fill.

A link. With href, its anchor lives in the shadow root and takes the focus for the element.

Without href the element itself is a button that looks like the link: it takes the button role and the tab stop, fires click on Enter and Space, and never submits a form. Its own aria-label, aria-expanded and aria-controls name and describe that button, so it can open a popover or a disclosure. role="button" and tabindex="0" count as the kit's and leave when href comes; any other role or tabindex is the host's and stays.

AttributeTypeDescription
hrefstringWhere the link goes; without it the element is a button. With it, the anchor is named by the element's own aria-label, as a link of an icon alone needs, or else by its content.
targetstringWhere to open the link.
relstringHow the target relates to the page.
variantstringWhich palette of color the link takes its color from: secondary, quiet text, or a variant of the host's own; without it, the link color.
appearanceunderline, plainHow the link is drawn: underline, the default, in the font of the text around it; plain, for a link on its own, without an underline, in the text of a field hint, at least 24px high. Only the attribute sets it.
sizexsmall, small, medium, large, xlargeHow large a plain link is: its text is one step smaller than the text of the size, at least 12px; medium by default. A link in text takes the font around it.

Properties and methods:

  • focus(): Focuses the anchor with href, and the element itself without it.
SlotDescription
(default)The text of the link.
startAn icon before the text, 2px larger than it.
endAn icon after the text, 2px larger than it.
CSS partDescription
linkThe anchor, or the content of the button without href.
StateDescription
plainThe link is plain.
start-contentThe link has content in its start slot.
end-contentThe link has content in its end slot.

A text field: a native input with its label, hint and error, rendered into light DOM.

AttributeTypeDescription
labelstringThe label of the field.
optionalstringA marker after the label, such as (optional), in the host's language; it joins the field's name.
hintstringHelp text under the field.
errorstringThe error shown while the field is invalid.
invalidbooleanMarks the field invalid and shows the error.
valuestringThe default value.
typetext, email, tel, password, number, search, urlThe kind of value; text by default.
appearanceoutline, filled, underlineHow the field is drawn; the configured setting by default.
sizexsmall, small, medium, large, xlargeHow large the field is; medium by default. At xsmall the label sits above the field.
disabledbooleanDisables the field.
readonlybooleanMakes the field read-only.
requiredbooleanMakes the field required.
namestringThe name sent with the form.
placeholderstringText shown while the field is empty.
autocompletestringThe autofill hint of the native input.
inputmodestringThe virtual keyboard to show.
minlengthnumberThe shortest allowed value.
maxlengthnumberThe longest allowed value.
patternstringThe pattern the value matches.
minstringThe smallest allowed value.
maxstringThe largest allowed value.
stepstringThe step between allowed values.

Properties and methods:

  • focus(): Focuses the element.
EventDescription
inputThe value changes as the user types; it bubbles from the native input.
changeThe user commits a new value; it bubbles from the native input.
SlotDescription
hintHelp content under the field in place of the hint text, such as "Did you mean gmail.com?"; it describes the input, and hiding it with hidden brings the hint text back.
startContent before the text, such as an icon; an svg is drawn 4px larger than the text, in the quiet color.
endContent after the text, such as a card logo, a check or a button; hide it with hidden, and disable a button in it along with the field.
CSS partDescription
frameThe box that draws the field around the native input, its start and its end.
startThe box of the start content.
endThe box of the end content.
StateDescription
outlineThe field has a border on all sides.
filledThe field has a fill and a bottom border.
underlineThe field has a bottom border.
aboveThe label sits above the field.
floatingThe label floats inside the field.

A text field for several lines: a native textarea with its label, hint and error, rendered into light DOM. Enter adds a line; the field grows only when the user drags its corner.

AttributeTypeDescription
labelstringThe label of the field.
optionalstringA marker after the label, such as (optional), in the host's language; it joins the field's name.
hintstringHelp text under the field.
errorstringThe error shown while the field is invalid.
invalidbooleanMarks the field invalid and shows the error.
valuestringThe default value.
appearanceoutline, filled, underlineHow the field is drawn; the configured setting by default.
sizexsmall, small, medium, large, xlargeHow large the field is; medium by default. At xsmall the label sits above the field.
disabledbooleanDisables the field.
readonlybooleanMakes the field read-only.
requiredbooleanMakes the field required.
namestringThe name sent with the form.
placeholderstringText shown while the field is empty.
autocompletestringThe autofill hint of the native textarea.
minlengthnumberThe shortest allowed value.
maxlengthnumberThe longest allowed value.
rowsnumberThe visible lines; 2 by default.

Properties and methods:

  • focus(): Focuses the element.
EventDescription
inputThe value changes as the user types; it bubbles from the native textarea.
changeThe user commits a new value; it bubbles from the native textarea.
SlotDescription
hintHelp content under the field in place of the hint text; it describes the textarea, and hiding it with hidden brings the hint text back.
CSS partDescription
frameThe box that draws the field around the native textarea.
StateDescription
outlineThe field has a border on all sides.
filledThe field has a fill and a bottom border.
underlineThe field has a bottom border.
aboveThe label sits above the field.
floatingThe label floats inside the field.

A select: a field that opens a list of its <swell-select-option> children and shows the chosen one, with its start content; an svg there is drawn 4px larger than the text, in the quiet color. It holds the choice and takes part in its form. Typing goes to the option whose label starts with the typed text, as on a native select: keys typed within half a second, spaces included, form one search.

AttributeTypeDescription
labelstringThe label of the field. Without it, the select takes its name from its own aria-label.
optionalstringA marker after the label, such as (optional), in the host's language; it joins the select's name.
hintstringHelp text under the field.
errorstringThe error shown while the select is invalid.
invalidbooleanMarks the select invalid and shows the error.
namestringThe name sent with the form.
valuestringThe value of the option chosen by default.
placeholderstringText shown while nothing is chosen.
requiredbooleanThe form can't be sent until an option is chosen.
disabledbooleanDisables the select.
autocompletestringThe browser's autofill hint, such as country or address-level1, as on a native select: autofill picks the enabled option whose value or label matches the saved one, which counts as the user's choice and fires input and change.
aria-labelThe element's accessible name, when it has no visible label.
appearanceoutline, filled, underlineHow the field is drawn; the configured setting by default.
sizexsmall, small, medium, large, xlargeHow large the field is; medium by default. At xsmall the label sits above the field.

Properties and methods:

  • checkValidity(): Checks the field's validity, as on a native field.
  • reportValidity(): Checks the field's validity and shows its error, as on a native field.
  • focus(): Focuses the element.
EventDescription
inputThe user chose another option.
changeThe user chose another option, after input.
SlotDescription
(default)The options, elements; a hidden one stays out of the list and the choice.
StateDescription
outlineThe field has a border on all sides.
filledThe field has a fill and a bottom border.
underlineThe field has a bottom border.
aboveThe label sits above the field.
floatingThe label floats inside the field.
emptyNothing is chosen.
openThe list is open.

One option of a select. It lives only as a direct child of <swell-select>, which holds the choice.

AttributeTypeDescription
valuestringThe value the select takes when the option is chosen; the option's label by default.
hintstringA second line under the label.
disabledbooleanDisables the option.
hidden

Properties and methods:

  • selected: Whether the option is chosen; the select sets it.
  • label: The text of the option's label: its text and its elements outside a named slot, without the comments a framework leaves.
SlotDescription
(default)The label of the option.
startContent before the label, such as an icon or an image; an svg is drawn 1px larger than the text, in the quiet color.
StateDescription
selectedThe option is chosen.
disabledThe option is disabled.
firstThe option is the first one on show; it draws no divider above it.

A text field with suggestions: a combobox in ARIA terms. The host loads the suggestions, such as addresses, and puts them into a <swell-lookup-list> child as <swell-lookup-option> elements; the field shows them under itself. It is a <swell-input> in everything else: its native input stays in light DOM, so autofill works as in any field.

The list opens while the user types and it has something to show, and closes on a choice, on Escape and when the focus leaves the field. Choosing a suggestion clicks it. After the click, unless a handler prevented its default, the field writes the suggestion's label into the input and fires input, with inputType insertReplacementText, and change; the list stays closed until the user types again.

AttributeTypeDescription
labelstringThe label of the field.
optionalstringA marker after the label, such as (optional), in the host's language; it joins the field's name.
hintstringHelp text under the field.
errorstringThe error shown while the field is invalid.
invalidbooleanMarks the field invalid and shows the error.
valuestringThe default value.
typetext, email, tel, password, number, search, urlThe kind of value; text by default.
appearanceoutline, filled, underlineHow the field is drawn; the configured setting by default.
sizexsmall, small, medium, large, xlargeHow large the field is; medium by default. At xsmall the label sits above the field.
disabledbooleanDisables the field.
readonlybooleanMakes the field read-only.
requiredbooleanMakes the field required.
namestringThe name sent with the form.
placeholderstringText shown while the field is empty.
autocompletestringThe autofill hint of the native input.
inputmodestringThe virtual keyboard to show.
minlengthnumberThe shortest allowed value.
maxlengthnumberThe longest allowed value.
patternstringThe pattern the value matches.
minstringThe smallest allowed value.
maxstringThe largest allowed value.
stepstringThe step between allowed values.

Properties and methods:

  • focus(): Focuses the element.
EventDescription
inputThe value changes as the user types; it bubbles from the native input.
changeThe user commits a new value; it bubbles from the native input.
SlotDescription
(default)The list of suggestions, a . While it is there, the input is a combobox and the list can open: keep it in the field, even empty, for as long as the field takes suggestions.
hintHelp content under the field in place of the hint text, as on an input.
actionA row at the end of the list, such as a
startContent before the text, such as an icon; an svg is drawn 4px larger than the text, in the quiet color.
endContent after the text, such as a card logo, a check or a button; hide it with hidden, and disable a button in it along with the field.
CSS partDescription
listThe popup that holds the list and the action.
frameThe box that draws the field around the native input, its start and its end.
startThe box of the start content.
endThe box of the end content.
StateDescription
outlineThe field has a border on all sides.
filledThe field has a fill and a bottom border.
underlineThe field has a bottom border.
aboveThe label sits above the field.
floatingThe label floats inside the field.

The list of a lookup's suggestions. It lives only as a child of <swell-lookup>, which shows it under the field while it opens.

SlotDescription
(default)The suggestions, elements.

One suggestion of a lookup. It lives only as a child of <swell-lookup-list>. Choosing it clicks it: the host reads the option from the click. A click on a disabled suggestion reaches the host's handlers too, and the field ignores it.

AttributeTypeDescription
valuestringThe value of the suggestion, such as the id of a place; the label by default.
hintstringA second line under the label.
disabledbooleanDisables the suggestion.
hidden

Properties and methods:

  • selected: Whether the option is chosen; the select sets it.
  • label: The text of the option's label: its text and its elements outside a named slot, without the comments a framework leaves.
SlotDescription
(default)The label of the suggestion; the field writes its text into the input when it is chosen.
startContent before the label, such as an icon.
StateDescription
focusedThe field's keyboard points at the suggestion.
disabledThe suggestion is disabled.
firstThe option is the first one on show; it draws no divider above it.

A checkbox: a native checkbox with its label, hint and error, rendered into light DOM.

AttributeTypeDescription
labelstringThe label beside the box.
hintstringHelp text under the checkbox.
errorstringThe error shown while the checkbox is invalid.
invalidbooleanMarks the checkbox invalid and shows the error.
checkedbooleanThe default state.
valuestringThe value sent with the form; on by default.
disabledbooleanDisables the checkbox.
requiredbooleanMakes the checkbox required.
namestringThe name sent with the form.
sizexsmall, small, medium, large, xlargeHow large the checkbox is: the label takes the text of the size and the box grows with it; medium by default. The target stays at least 24px.

Properties and methods:

  • focus(): Focuses the element.
EventDescription
changeThe user checks or unchecks the box; it bubbles from the native input.

A radio group: a question with one answer, chosen from its <swell-radio-option> children. It holds the choice and takes part in its form.

AttributeTypeDescription
labelstringThe question. Without it, the group takes its name from its own aria-label.
hintstringHelp text under the options.
errorstringThe error shown while the group is invalid.
invalidbooleanMarks the group invalid and shows the error.
namestringThe name sent with the form.
valuestringThe value of the option chosen by default.
requiredbooleanThe form can't be sent until an option is chosen.
disabledbooleanDisables every option.
aria-labelThe element's accessible name, when it has no visible label.
indicator-positionstart, endWhere the circle sits in the row of each option; the radio.indicator.position setting gives the default. A segmented group draws no circle.
sizexsmall, small, medium, large, xlargeHow large the options are: their text, circle and padding follow the text of the size, and a segmented track takes the height of a control; medium by default.
appearanceplain, outline, segmented, buttonHow the options are drawn: the circle and the label, each option in a frame, the options sharing a track like a switch, or each option as a button in equal columns. segmented suits two or three short options, button short options such as languages or sizes; both are set with this attribute only. The radio.appearance setting gives the default.

Properties and methods:

  • checkValidity(): Checks the field's validity, as on a native field.
  • reportValidity(): Checks the field's validity and shows its error, as on a native field.
  • focus(): Focuses the group's Tab stop, as a Tab into the group does.
EventDescription
inputThe user chose another option.
changeThe user chose another option, after input. Events of fields in the options' details bubble through the group too: the group's own have it as their target.
SlotDescription
(default)The options, elements.
StateDescription
plainThe options are drawn plain.
outlineEach option is drawn in a frame.
segmentedThe options share a track.
buttonEach option is drawn as a button.

One option of a radio group. It lives only as a direct child of <swell-radio>, which holds the choice. In a segmented group and as a button an option shows its start and its label; its hint, end and details are not drawn. An option with the hidden attribute is left out of its group.

AttributeTypeDescription
valuestringThe value the group takes when the option is chosen; on by default.
hintstringHelp text under the label.
disabledbooleanDisables the option.
hidden

Properties and methods:

  • checked: Whether the option is chosen; the group sets it.
SlotDescription
(default)The label of the option.
startContent before the label, such as an icon or a logo; decoration, left out of the option's name.
endContent at the end of the row, such as a price or logos.
detailsContent shown while the option is chosen, such as card fields. While hidden it stays in the page and in the form: render it only while the option is chosen, or disable its fields.
StateDescription
plainThe group draws its options plain: the circle and the label.
outlineThe group draws each option in a frame.
segmentedThe group draws its options as segments of one track.
buttonThe group draws each option as a button.
startThe circle sits at the start of the row.
endThe circle sits at the end of the row.
checkedThe option is chosen.
disabledThe option or its group is disabled.
invalidThe group is invalid.
start-contentThe option has content in its start slot.
detailsThe option has content in its details slot.
focusedThe option's radio has the keyboard focus.

A quantity: a count the shopper changes with − and +, such as the quantity of a cart line or of a product before it goes into the cart. It is a spinbutton with one tab stop: the up and down arrows change the count by step, and Home and End move it to min and max. Name it with aria-label, such as Quantity, House Blend, or with aria-labelledby. It holds the count and takes part in its form. While the cart updates, set busy rather than disabled: a disabled quantity leaves the tab order, so disabling the focused one drops the focus to the page.

AttributeTypeDescription
valuenumberThe starting count, a whole number; min by default. A count outside the limits is clamped, and a count the user or a script set stays at the limit that clamped it.
minnumberThe least count, a whole number; 1 by default.
maxnumberThe greatest count, a whole number; no limit by default. A max below min counts as min.
stepnumberHow much each step changes the count, a whole number above 0; 1 by default.
disabledbooleanRemoves the quantity from the tab order and ignores steps.
busybooleanThe quantity waits, such as while the cart updates: it keeps the focus, its count and its tab stop, ignores steps, fades and tells screen readers it is busy; a script can still set its count.
namestringThe name sent with the form.
sizexsmall, small, medium, large, xlargeHow large the quantity is: it shares a height with buttons and fields of its size; medium by default. A cart line takes xsmall.
EventDescription
inputThe user changed the count.
changeThe user changed the count, after input.

A chip: a short value the shopper can remove, such as an applied discount code or gift card. Its remove button fires remove; the host removes the chip and moves the focus, for example to the code field. A disabled chip, by its own attribute or a disabled fieldset around it, keeps its value legible and fades its remove button, which takes neither the focus nor presses, so a host can lock a form while it is sent.

AttributeTypeDescription
disabledbooleanDisables the remove button.
remove-labelstringThe name of the remove button in the host's language, such as Remove WELCOME10; every chip needs one.
sizexsmall, small, medium, large, xlargeHow large the chip is; medium by default. Its remove button is as high as the chip, at least 24px.

Properties and methods:

  • focus(): Focuses the remove button, the chip's only stop, so a host can hand the focus to a chip; a click on the text leaves the focus alone.
EventDescription
removeThe shopper pressed the remove button; it bubbles, and the chip stays in the page. A disabled chip fires none.
SlotDescription
(default)The value.
startAn icon before the value, drawn 2px larger than the text.
CSS partDescription
removeThe remove button.

Tabs: a set of <swell-tab> children, one of them chosen, with its content shown. The group draws a tab list: a tab per child, named by its label. The arrows move between the tabs and Home and End to the ends; underlined and segmented tabs are chosen as the focus moves, steps with Enter or Space. Vertical steps draw no tab list: each step is a heading with a button that opens it, and Tab moves between the buttons.

AttributeTypeDescription
valuestringThe value of the chosen tab; the first tab that isn't disabled by default.
aria-labelThe element's accessible name, when it has no visible label.
orientationhorizontal, verticalHow steps line up: in a row above the chosen step's content, by default, or one under another, each a heading with its content under it. Other appearances stay in a row.
levelnumberThe heading level of vertical steps, 1 to 6; 2 by default.
done-labelstringThe word a screen reader hears after the label of a done step, in the host's language, such as Completed; the check shows it to the eye.
appearanceunderline, segmented, stepsHow the tabs are drawn: a line under the chosen tab, a track with a marker under it, or numbered steps joined by lines, each a check once done. steps is set with this attribute only; the tabs.appearance setting gives the default.
sizexsmall, small, medium, large, xlargeHow large the tabs are: they take the height and the text of a control of the size; medium by default.
EventDescription
changeThe user chose another tab. A listener that cancels the click on a tab, also a framework's handler on the page, keeps the choice.
requestThe user asks for another tab, by a press or an arrow, with its value in detail.value, before the group chooses it; it bubbles. Cancelling it keeps the choice. It fires for a disabled tab too, which stays unchosen, so a host can answer a press on a locked step, such as by checking the open one.
SlotDescription
(default)The tabs, elements.
StateDescription
underlineA line marks the chosen tab.
segmentedThe tabs share a track.
stepsThe tabs are numbered steps.
verticalThe steps stand one under another.

A tab of a <swell-tabs> group: its label and its content, shown while it is chosen. In a tab list the group draws the tab and the element is its panel, named by the label; role="tabpanel" and that name count as the kit's. A step of vertical steps draws its own heading at the group's level, holding a button that opens it, tells whether it is open and controls its content under the heading.

AttributeTypeDescription
valuestringThe group's value while the tab is chosen; the label by default.
labelstringThe text of the tab or of the step's heading.
donebooleanMarks a step as done: its number becomes a check, and the line to the next step fills.
disabledbooleanThe tab can't be chosen, such as a step that isn't open yet.
hidden
SlotDescription
(default)The content, shown while the tab is chosen.
summaryVertical steps: content under the heading while the step is closed, such as what a done step holds or what a step that isn't open yet will ask.
endVertical steps: content beside the heading, such as a link that opens a done step or a note.
StateDescription
selectedThe tab is chosen.
verticalThe tab is a step of vertical steps.
lastThe tab is the last of its group, so a vertical step draws no line to a next one.

A disclosure: content that stays hidden until the shopper presses its trigger, such as "Add apartment, suite, etc." and the field it reveals. The trigger opens it and leaves; the focus moves to the first control of the content. With toggle, such as a collapsible order summary, the trigger stays, closes the content too and tells whether it is open with aria-expanded; the focus stays on it. The host can also set open itself, for example from a checkbox, and remove it to close the content and bring the trigger back; without a trigger, the host moves the focus out first. Closed content stays in the page and in the form: render it only while open, or disable its fields, so a required field doesn't block the submit.

AttributeTypeDescription
openbooleanShows the content and hides the trigger. Set on connect, the content shows at once.
togglebooleanKeeps the trigger while the content is open: it closes the content too and carries aria-expanded.
EventDescription
toggleThe content opened or closed: by the trigger or by script, also as it starts open. A ToggleEvent with oldState and newState, fired once the script that changed open has run; it doesn't bubble and can't be cancelled.
SlotDescription
triggerThe host's button that opens the content, such as ; a button, not a link with href. Inside a form a
(default)The content.
CSS partDescription
contentThe box that expands to show the content.
StateDescription
closingThe content collapses; the trigger is back, out of the flow and invisible until it ends.

A popover: a small dialog that floats at the host's trigger, such as the language and currency picker of a checkout. The trigger opens and closes it; opened by the trigger, it moves the focus to its first control. Escape closes it and gives the focus back to the trigger; a press outside it and the focus leaving it close it too. A choice inside keeps it open. The panel sits under the trigger, or above it when there is more room there, at the trigger's start edge, or at its end edge when it would leave the window there. Its content sets its width, at least the trigger's and at most the window's less 16px. Name it with aria-label, such as Language and currency.

AttributeTypeDescription
openbooleanThe panel is open. Set it to open the panel without moving the focus; remove it to close the panel, which gives the focus back to the trigger when the focus is inside.
aria-labelThe element's accessible name, when it has no visible label.
EventDescription
toggleThe panel opened or closed: by the trigger, Escape, a press outside, the focus leaving it or script, also as it starts open or leaves the page open. A ToggleEvent with oldState and newState, fired once the script that changed open has run; it doesn't bubble and can't be cancelled.
SlotDescription
triggerThe host's button that opens and closes the panel: a
(default)The content of the panel.
CSS partDescription
panelThe floating panel.

An area of the page with token values of its own, such as an order summary in the colors of the brand. The host registers the area's configuration with configure(config, id); its tokens and theme apply to everything inside the element, the host's own markup included, and every value it leaves out comes from the page. The element keeps the layout of its content: it renders nothing of its own.

AttributeTypeDescription
configstringThe id of the area's configuration. An id without a configuration yet applies once the host registers one.