js/webawesome
1
0
Fork 0
mirror of https://github.com/shoelace-style/webawesome.git synced 2026-01-12 12:09:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

new docs

Browse Source
This commit is contained in:
Cory LaViska
2023-06-06 08:22:18 -04:00
parent 0866785495
commit de5ad1b1b9
116 changed files with 27829 additions and 2671 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -1,5 +1,6 @@
.DS_Store
.cache
_site
docs/dist
docs/search.json
dist

4
README.md
View File

@@ -51,9 +51,7 @@ Once you've cloned the repo, run the following command.
npm start
```
This will spin up the Shoelace dev server. After the initial build, a browser will open automatically. There is currently no hot module reloading (HMR), as browser's don't provide a way to reregister custom elements, but most changes to the source will reload the browser automatically.
The documentation is powered by Docsify, which uses raw markdown files to generate pages. As such, no static files are built for the docs.
This will spin up the dev server. After the initial build, a browser will open automatically. There is currently no hot module reloading (HMR), as browser's don't provide a way to reregister custom elements, but most changes to the source will reload the browser automatically.
### Building

3
cspell.json
View File

@@ -81,6 +81,7 @@
"labelledby",
"Laravel",
"LaViska",
"linkify",
"listbox",
"listitem",
"litelement",
@@ -105,6 +106,7 @@
"ParamagicDev",
"peta",
"petabit",
"prismjs",
"progressbar",
"radiogroup",
"Railsbyte",
@@ -127,6 +129,7 @@
"Segoe",
"semibold",
"slotchange",
"smartquotes",
"spacebar",
"stylesheet",
"Tabbable",

347
docs/_includes/component.njk Normal file
View File

@@ -0,0 +1,347 @@
{% extends "default.njk" %}
{# Find the component based on the `tag` front matter #}
{% set component = getComponent('sl-' + page.fileSlug) %}
{% block content %}
{# Determine the badge variant #}
{% if component.status == 'stable' %}
{% set badgeVariant = 'primary' %}
{% elseif component.status == 'experimental' %}
{% set badgeVariant = 'warning' %}
{% elseif component.status == 'planned' %}
{% set badgeVariant = 'neutral' %}
{% elseif component.status == 'deprecated' %}
{% set badgeVariant = 'danger' %}
{% else %}
{% set badgeVariant = 'neutral' %}
{% endif %}
{# Header #}
<header class="component-header">
<h1>{{ component.name | classNameToComponentName }}</h1>
<div class="component-header__tag">
<code>&lt;{{ component.tagName }}&gt; | {{ component.name }}</code>
</div>
<div class="component-header__info">
<sl-badge variant="neutral" pill>
Since {{component.since or '?' }}
</sl-badge>
<sl-badge variant="{{ badgeVariant }}" pill style="text-transform: capitalize;">
{{ component.status }}
</sl-badge>
</div>
</header>
<p class="component-summary">
{% if component.summary %}
{{ component.summary | markdownInline | safe }}
{% endif %}
</p>
{# Markdown content #}
{{ content | safe }}
{# Importing #}
<h2>Importing</h2>
<p>
If you're using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use
any of the following snippets to <a href="/getting-started/installation#cherry-picking">cherry pick</a> this component.
</p>
<sl-tab-group>
<sl-tab slot="nav" panel="script">Script</sl-tab>
<sl-tab slot="nav" panel="import">Import</sl-tab>
<sl-tab slot="nav" panel="bundler">Bundler</sl-tab>
<sl-tab slot="nav" panel="react">React</sl-tab>
<sl-tab-panel name="script">
<p>
To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">the CDN</a>
using a script tag:
</p>
<pre><code class="language-html">&lt;script type=&quot;module&quot; src=&quot;https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/dist/{{ component.path }}&quot;&gt;&lt;/script&gt;</code></pre>
</sl-tab-panel>
<sl-tab-panel name="import">
<p>
To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">the CDN</a>
using a JavaScript import:
</p>
<pre><code class="language-js">import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/dist/{{ component.path }}';</code></pre>
</sl-tab-panel>
<sl-tab-panel name="bundler">
<p>
To import this component using <a href="{{ rootUrl('/getting-started/installation#bundling') }}">a bundler</a>:
</p>
<pre><code class="language-js">import '@shoelace-style/shoelace/dist/{{ component.path }}';</code></pre>
</sl-tab-panel>
<sl-tab-panel name="react">
<p>
To import this component as a <a href="/frameworks/react">React component</a>:
</p>
<pre><code class="language-js">import { {{ component.name }} } from '@shoelace-style/shoelace/dist/react';</code></pre>
</sl-tab-panel>
</sl-tab-group>
{# Slots #}
{% if component.slots.length %}
<h2>Slots</h2>
<table>
<thead>
<tr>
<th class="table-name">Name</th>
<th class="table-description">Description</th>
</tr>
</thead>
<tbody>
{% for slot in component.slots %}
<tr>
<td class="nowrap">
{% if slot.name %}
<code>{{ slot.name }}</code>
{% else %}
(default)
{% endif %}
</td>
<td>{{ slot.description | markdownInline | safe }}</td>
</tr>
{% endfor %}
</tbody>
</table>
<p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#slots') }}">using slots</a>.</em></p>
{% endif %}
{# Properties #}
{% if component.properties.length %}
<h2>Properties</h2>
<table>
<thead>
<tr>
<th class="table-name">Name</th>
<th class="table-description">Description</th>
<th class="table-reflects">Reflects</th>
<th class="table-type">Type</th>
<th class="table-default">Default</th>
</tr>
</thead>
<tbody>
{% for prop in component.properties %}
<tr>
<td>
<code class="nowrap">{{ prop.name }}</code>
{% if prop.attribute != prop.name %}
<br>
<sl-tooltip content="This attribute is different from its property">
<small>
<code class="nowrap">
{{ prop.attribute }}
</code>
</small>
</sl-tooltip>
{% endif %}
</td>
<td>
{{ prop.description | markdownInline | safe }}
</td>
<td style="text-align: center;">
{% if prop.reflects %}
<sl-icon label="yes" name="check-lg"></sl-icon>
{% endif %}
</td>
<td>
{% if prop.type.text %}
<code>{{ prop.type.text | markdownInline | safe }}</code>
{% else %}
-
{% endif %}
</td>
<td>
{% if prop.default %}
<code>{{ prop.default | markdownInline | safe }}</code>
{% else %}
-
{% endif %}
</td>
</tr>
{% endfor %}
<tr>
<td class="nowrap"><code>updateComplete</code></td>
<td>
A read-only promise that resolves when the component has
<a href="/getting-started/usage?id=component-rendering-and-updating">finished updating</a>.
</td>
<td></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#properties') }}">attributes and properties</a>.</em></p>
{% endif %}
{# Events #}
{% if component.events.length %}
<h2>Events</h2>
<table>
<thead>
<tr>
<th class="table-name" data-flavor="html">Name</th>
<th class="table-name" data-flavor="react">React Event</th>
<th class="table-description">Description</th>
<th class="table-event-detail">Event Detail</th>
</tr>
</thead>
<tbody>
{% for event in component.events %}
<tr>
<td data-flavor="html"><code class="nowrap">{{ event.name }}</code></td>
<td data-flavor="react"><code class="nowrap">{{ event.reactName }}</code></td>
<td>{{ event.description | markdownInline | safe }}</td>
<td>
{% if event.type.text %}
<code>{{ event.type.text }}</code>
{% else %}
-
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
<p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#events') }}">events</a>.</em></p>
{% endif %}
{# Methods #}
{% if component.methods.length %}
<h2>Methods</h2>
<table>
<thead>
<tr>
<th class="table-name">Name</th>
<th class="table-description">Description</th>
<th class="table-arguments">Arguments</th>
</tr>
</thead>
<tbody>
{% for method in component.methods %}
<tr>
<td class="nowrap"><code>{{ method.name }}()</code></td>
<td>{{ method.description | markdownInline | safe }}</td>
<td>
{% if method.parameters.length %}
<code>
{% for param in method.parameters %}
{{ param.name }}: {{ param.type.text }}{% if not loop.last %},{% endif %}
{% endfor %}
</code>
{% else %}
-
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
<p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#methods') }}">methods</a>.</em></p>
{% endif %}
{# Custom Properties #}
{% if component.cssProperties.length %}
<h2>Custom Properties</h2>
<table>
<thead>
<tr>
<th class="table-name">Name</th>
<th class="table-description">Description</th>
<th class="table-default">Default</th>
</tr>
</thead>
<tbody>
{% for cssProperty in component.cssProperties %}
<tr>
<td class="nowrap"><code>{{ cssProperty.name }}</code></td>
<td>{{ cssProperty.description | markdownInline | safe }}</td>
<td>{{ cssProperty.default }}</td>
</tr>
{% endfor %}
</tbody>
</table>
<p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#custom-properties') }}">customizing CSS custom properties</a>.</em></p>
{% endif %}
{# CSS Parts #}
{% if component.cssParts.length %}
<h2>Parts</h2>
<table>
<thead>
<tr>
<th class="table-name">Name</th>
<th class="table-description">Description</th>
</tr>
</thead>
<tbody>
{% for cssPart in component.cssParts %}
<tr>
<td class="nowrap"><code>{{ cssPart.name }}</code></td>
<td>{{ cssPart.description | markdownInline | safe }}</td>
</tr>
{% endfor %}
</tbody>
</table>
<p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#component-parts') }}">customizing CSS parts</a>.</em></p>
{% endif %}
{# Animations #}
{% if component.animations.length %}
<h2>Animations</h2>
<table>
<thead>
<tr>
<th class="table-name">Name</th>
<th class="table-description">Description</th>
</tr>
</thead>
<tbody>
{% for animation in component.animations %}
<tr>
<td class="nowrap"><code>{{ animation.name }}</code></td>
<td>{{ animation.description | markdownInline | safe }}</td>
</tr>
{% endfor %}
</tbody>
</table>
<p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#animations') }}">customizing animations</a>.</em></p>
{% endif %}
{# Dependencies #}
{% if component.dependencies.length %}
<h2>Dependencies</h2>
<p>This component automatically imports the following dependencies.</p>
<ul>
{% for dependency in component.dependencies %}
<li><code>&lt;{{ dependency }}&gt;</code></li>
{% endfor %}
</ul>
{% endif %}
{% endblock %}

143
docs/_includes/default.njk Normal file
View File

@@ -0,0 +1,143 @@
<!DOCTYPE html>
<html
lang="en"
data-layout="{{ layout }}"
data-shoelace-version="{{ meta.version }}"
>
<head>
{# Metadata #}
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="{{ meta.description }}" />
<title>{{ meta.title }}</title>
{# Stylesheets #}
<link rel="stylesheet" href="{{ assetUrl('styles/docs.css') }}" />
<link rel="stylesheet" href="{{ assetUrl('styles/code-previews.css') }}" />
<link rel="stylesheet" href="{{ assetUrl('styles/search.css') }}" />
{# Favicons #}
<link rel="icon" href="{{ assetUrl('images/logo.svg') }}" type="image/x-icon" />
{# Twitter Cards #}
<meta name="twitter:card" content="summary" />
<meta name="twitter:creator" content="shoelace_style" />
<meta name="twitter:image" content="{{ assetUrl(meta.image, true) }}" />
{# OpenGraph #}
<meta property="og:url" content="{{ rootUrl(page.url, true) }}" />
<meta property="og:title" content="{{ meta.title }}" />
<meta property="og:description" content="{{ meta.description }}" />
<meta property="og:image" content="{{ assetUrl(meta.image, true) }}" />
{# Shoelace #}
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.4.0/dist/themes/light.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.4.0/dist/themes/dark.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.4.0/dist/shoelace-autoloader.js"></script>
{# Set the initial theme and menu states here to prevent flashing #}
<script>
(() => {
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const theme = localStorage.getItem('theme');
document.documentElement.classList.toggle('sl-theme-dark', theme === 'dark' || (!theme && prefersDark));
})();
</script>
</head>
<body>
<a id="skip-to-main" class="visually-hidden" href="#main-content" data-smooth-link="false">
Skip to main content
</a>
{# Menu toggle #}
<button id="menu-toggle" type="button" aria-label="Menu">
<svg width="148" height="148" viewBox="0 0 148 148" xmlns="http://www.w3.org/2000/svg">
<g stroke="currentColor" stroke-width="18" fill="none" fill-rule="evenodd" stroke-linecap="round">
<path d="M9.5 125.5h129M9.5 74.5h129M9.5 23.5h129"></path>
</g>
</svg>
</button>
{# Icon toolbar #}
<div id="icon-toolbar">
{# GitHub #}
<a href="https://github.com/shoelace-style/shoelace" title="View Shoelace on GitHub">
<sl-icon name="github"></sl-icon>
</a>
{# Twitter #}
<a href="https://twitter.com/shoelace_style" title="Follow Shoelace on Twitter">
<sl-icon name="twitter"></sl-icon>
</a>
{# Theme toggle #}
<button
id="theme-toggle"
type="button"
aria-label="Toggle light and dark theme"
title="Toggle theme (press backslash)"
>
<sl-icon class="only-light" name="sun-fill"></sl-icon>
<sl-icon class="only-dark" name="moon-fill"></sl-icon>
</button>
</div>
<aside id="sidebar">
<header>
<a href="/">
<img src="{{ assetUrl('images/wordmark.svg') }}" alt="Shoelace" />
</a>
<div class="sidebar-version">
{{ meta.version }}
</div>
</header>
<div class="sidebar-buttons">
<sl-button size="small" class="repo-button repo-button--sponsor" href="https://github.com/sponsors/claviska" target="_blank">
<sl-icon slot="prefix" name="heart"></sl-icon> Sponsor
</sl-button>
<sl-button size="small" class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace" target="_blank">
<sl-icon slot="prefix" name="github"></sl-icon> Code
</sl-button>
<sl-button size="small" class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
<sl-icon slot="prefix" name="twitter"></sl-icon> Follow
</sl-button>
</div>
<button class="search-box" type="button" title="Press / to search" aria-label="Search" data-plugin="search">
<sl-icon name="search"></sl-icon>
<span>Search</span>
</button>
<nav>
{% include 'sidebar.njk' %}
</nav>
</aside>
{# Content #}
<main>
<a id="main-content"></a>
<article id="content" class="content{% if toc %} content--with-toc{% endif %}">
{% if toc %}
<div class="content__toc">
<ul>
<li class="top"><a href="#">{{ meta.title }}</a></li>
</ul>
</div>
{% endif %}
<div class="content__body">
{% block content %}
{{ content | safe }}
{% endblock %}
</div>
</article>
</main>
{# Scripts #}
<script src="{{ assetUrl('scripts/docs.js') }}"></script>
<script src="{{ assetUrl('scripts/code-previews.js') }}"></script>
<script src="{{ assetUrl('scripts/lunr.js') }}"></script>
<script src="{{ assetUrl('scripts/search.js') }}"></script>
</body>
</html>

65
docs/_includes/sidebar.njk Normal file
View File

@@ -0,0 +1,65 @@
<ul>
<li>
<h2>Getting Started</h2>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/getting-started/installation">Installation</a></li>
<li><a href="/getting-started/usage">Usage</a></li>
<li><a href="/getting-started/themes">Themes</a></li>
<li><a href="/getting-started/customizing">Customizing</a></li>
<li><a href="/getting-started/form-controls">Form Controls</a></li>
<li><a href="/getting-started/localization">Localization</a></li>
</ul>
</li>
<li>
<h2>Frameworks</h2>
<ul>
<li><a href="/frameworks/react">React</a></li>
<li><a href="/frameworks/vue">Vue</a></li>
<li><a href="/frameworks/angular">Angular</a></li>
</ul>
</li>
<li>
<h2>Resources</h2>
<ul>
<li><a href="/resources/community">Community</a></li>
<li><a href="https://github.com/shoelace-style/shoelace/discussions">Help &amp; Support</a></li>
<li><a href="/resources/accessibility">Accessibility</a></li>
<li><a href="/resources/contributing">Contributing</a></li>
<li><a href="/resources/changelog">Changelog</a></li>
</ul>
</li>
<li>
<h2>Components</h2>
<ul>
{% for component in meta.components %}
<li>
<a href="/components/{{ component.tagName | removeSlPrefix }}">
{{ component.name | classNameToComponentName }}
</a>
</li>
{% endfor %}
</ul>
</li>
<li>
<h2>Design Tokens</h2>
<ul>
<li><a href="/tokens/typography">Typography</a></li>
<li><a href="/tokens/color">Color</a></li>
<li><a href="/tokens/spacing">Spacing</a></li>
<li><a href="/tokens/elevation">Elevation</a></li>
<li><a href="/tokens/border-radius">Border Radius</a></li>
<li><a href="/tokens/transition">Transition</a></li>
<li><a href="/tokens/z-index">Z-index</a></li>
<li><a href="/tokens/more">More</a></li>
</ul>
</li>
<li>
<h2>Tutorials</h2>
<ul>
<li><a href="/tutorials/integrating-with-laravel">Integrating with Laravel</a></li>
<li><a href="/tutorials/integrating-with-nextjs">Integrating with NextJS</a></li>
<li><a href="/tutorials/integrating-with-rails">Integrating with Rails</a></li>
</ul>
</li>
</ul>

35
docs/_utilities/active-links.cjs Normal file
View File

@@ -0,0 +1,35 @@
function normalizePathname(pathname) {
// Remove /index.html
if (pathname.endsWith('/index.html')) {
pathname = pathname.replace(/\/index\.html/, '');
}
// Remove trailing slashes
return pathname.replace(/\/$/, '');
}
/**
* Adds a class name to links that are currently active.
*/
module.exports = function (doc, options) {
options = {
className: 'active-link', // the class to add to active links
pathname: undefined, // the current pathname to compare
within: 'body', // element containing the target links
...options
};
const within = doc.querySelector(options.within);
if (!within) {
return doc;
}
within.querySelectorAll('a').forEach(link => {
if (normalizePathname(options.pathname) === normalizePathname(link.pathname)) {
link.classList.add(options.className);
}
});
return doc;
};

56
docs/_utilities/anchor-headings.cjs Normal file
View File

@@ -0,0 +1,56 @@
const { createSlug } = require('./strings.cjs');
/**
* Turns headings into clickable, deep linkable anchors. The provided doc should be a document object provided by JSDOM.
* The same document will be returned with the appropriate DOM manipulations.
*/
module.exports = function (doc, options) {
options = {
levels: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'], // the headings to convert
className: 'anchor-heading', // the class name to add
within: 'body', // the element containing the target headings
...options
};
const within = doc.querySelector(options.within);
if (!within) {
return doc;
}
within.querySelectorAll('h1, h2, h3, h4, h5, h6').forEach(heading => {
const hasAnchor = heading.querySelector('a');
const anchor = doc.createElement('a');
const slug = createSlug(heading.textContent ?? '') ?? '';
let id = slug;
let suffix = 0;
// If we can't generate a slug, skip this heading
if (!slug) return;
// Skip heading levels we don't care about
if (!options.levels?.includes(heading.tagName.toLowerCase())) {
return;
}
// Ensure the id is unique
while (doc.getElementById(id) !== null) {
id = `${slug}-${++suffix}`;
}
if (hasAnchor || !id) return;
heading.setAttribute('id', id);
anchor.setAttribute('href', `#${encodeURIComponent(id)}`);
anchor.setAttribute('aria-label', `Direct link to "${heading.textContent}"`);
if (options.className) {
heading.classList.add(options.className);
}
// Append the anchor
heading.append(anchor);
});
return doc;
};

74
docs/_utilities/cem.cjs Normal file
View File

@@ -0,0 +1,74 @@
//
// TODO - switch to local dist
//
const customElementsManifest = require('@shoelace-style/shoelace/dist/custom-elements.json');
//
// Export it here so we can import it elsewhere and use the same version
//
module.exports.customElementsManifest = customElementsManifest;
//
// Gets all components from custom-elements.json and returns them in a more documentation-friendly format.
//
module.exports.getAllComponents = function () {
const allComponents = [];
customElementsManifest.modules?.forEach(module => {
module.declarations?.forEach(declaration => {
if (declaration.customElement) {
// Generate the dist path based on the src path and attach it to the component
declaration.path = module.path.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
// Remove members that are private or don't have a description
const members = declaration.members?.filter(member => member.description && member.privacy !== 'private');
const methods = members?.filter(prop => prop.kind === 'method' && prop.privacy !== 'private');
const properties = members?.filter(prop => {
// Look for a corresponding attribute
const attribute = declaration.attributes?.find(attr => attr.fieldName === prop.name);
if (attribute) {
prop.attribute = attribute.name || attribute.fieldName;
}
return prop.kind === 'field' && prop.privacy !== 'private';
});
allComponents.push({
...declaration,
methods,
properties
});
}
});
});
// Build dependency graphs
allComponents.map(component => {
const dependencies = [];
// Recursively fetch sub-dependencies
function getDependencies(tag) {
const component = allComponents.find(c => c.tagName === tag);
if (!component || !Array.isArray(component.dependencies)) {
return;
}
component.dependencies?.forEach(dependentTag => {
if (!dependencies.includes(dependentTag)) {
dependencies.push(dependentTag);
}
getDependencies(dependentTag);
});
}
getDependencies(component.tagName);
component.dependencies = dependencies.sort();
});
// Sort by name
return allComponents.sort((a, b) => {
if (a.name < b.name) return -1;
if (a.name > b.name) return 1;
return 0;
});
};

153
docs/_utilities/code-previews.cjs Normal file
View File

@@ -0,0 +1,153 @@
let count = 1;
function escapeHtml(str) {
return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
}
/**
* Turns code fields with the :preview suffix into interactive code previews.
*/
module.exports = function (doc, options) {
options = {
within: 'body', // the element containing the code fields to convert
...options
};
const within = doc.querySelector(options.within);
if (!within) {
return doc;
}
within.querySelectorAll('[class*=":preview"]').forEach(code => {
const pre = code.closest('pre');
if (!pre) {
return;
}
const adjacentPre = pre.nextElementSibling?.tagName.toLowerCase() === 'pre' ? pre.nextElementSibling : null;
const reactCode = adjacentPre?.querySelector('code[class$="react"]');
const sourceGroupId = `code-preview-source-group-${count}`;
const toggleId = `code-preview-toggle-${count}`;
const isExpanded = code.getAttribute('class').includes(':expanded');
const noCodePen = code.getAttribute('class').includes(':no-codepen');
count++;
const htmlButton = `
<button type="button"
title="Show HTML code"
class="code-preview__button code-preview__button--html"
>
HTML
</button>
`;
const reactButton = `
<button type="button" title="Show React code" class="code-preview__button code-preview__button--react">
React
</button>
`;
const codePenButton = `
<button type="button" class="code-preview__button code-preview__button--codepen" title="Edit on CodePen">
<svg
width="138"
height="26"
viewBox="0 0 138 26"
fill="none"
stroke="currentColor"
stroke-width="2.3"
stroke-linecap="round"
stroke-linejoin="round"
>
<path d="M80 6h-9v14h9 M114 6h-9 v14h9 M111 13h-6 M77 13h-6 M122 20V6l11 14V6 M22 16.7L33 24l11-7.3V9.3L33 2L22 9.3V16.7z M44 16.7L33 9.3l-11 7.4 M22 9.3l11 7.3 l11-7.3 M33 2v7.3 M33 16.7V24 M88 14h6c2.2 0 4-1.8 4-4s-1.8-4-4-4h-6v14 M15 8c-1.3-1.3-3-2-5-2c-4 0-7 3-7 7s3 7 7 7 c2 0 3.7-0.8 5-2 M64 13c0 4-3 7-7 7h-5V6h5C61 6 64 9 64 13z" />
</svg>
</button>
`;
const codePreview = `
<div class="code-preview ${isExpanded ? 'code-preview--expanded' : ''}">
<div class="code-preview__preview">
${code.textContent}
<div class="code-preview__resizer">
<sl-icon name="grip-vertical"></sl-icon>
</div>
</div>
<div class="code-preview__source-group" id="${sourceGroupId}">
<div class="code-preview__source code-preview__source--html" ${reactCode ? 'data-flavor="html"' : ''}>
<pre><code class="language-html">${escapeHtml(code.textContent)}</code></pre>
</div>
${
reactCode
? `
<div class="code-preview__source code-preview__source--react" data-flavor="react">
<pre><code class="language-jsx">${escapeHtml(reactCode.textContent)}</code></pre>
</div>
`
: ''
}
</div>
<div class="code-preview__buttons">
<button
type="button"
class="code-preview__button code-preview__toggle"
aria-expanded="${isExpanded ? 'true' : 'false'}"
aria-controls="${sourceGroupId}"
>
Source
<svg
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
>
<polyline points="6 9 12 15 18 9"></polyline>
</svg>
</button>
${reactCode ? ` ${htmlButton} ${reactButton} ` : ''}
${noCodePen ? '' : codePenButton}
</div>
</div>
`;
pre.insertAdjacentHTML('afterend', codePreview);
pre.remove();
if (adjacentPre) {
adjacentPre.remove();
}
});
// Wrap code preview scripts in anonymous functions so they don't run in the global scope
doc.querySelectorAll('.code-preview__preview script').forEach(script => {
if (script.type === 'module') {
// Modules are already scoped
script.textContent = script.innerHTML;
} else {
// Wrap non-modules in an anonymous function so they don't run in the global scope
script.textContent = `(() => { ${script.innerHTML} })();`;
}
});
return doc;
};
function getAdjacentExample(name, pre) {
let currentPre = pre.nextElementSibling;
while (currentPre?.tagName.toLowerCase() === 'pre') {
if (currentPre?.getAttribute('class').indexOf(name) > -1) {
return currentPre;
}
currentPre = currentPre.nextElementSibling;
}
return null;
}

26
docs/_utilities/copy-code-buttons.cjs Normal file
View File

@@ -0,0 +1,26 @@
/**
* Adds copy code buttons to code fields. The provided doc should be a document object provided by JSDOM. The same
* document will be returned with the appropriate DOM manipulations.
*/
module.exports = function (doc) {
doc.querySelectorAll('pre > code').forEach(code => {
const pre = code.closest('pre');
const button = doc.createElement('button');
button.setAttribute('type', 'button');
button.classList.add('copy-code-button');
button.setAttribute('aria-label', 'Copy');
button.innerHTML = `
<svg class="copy-code-button__copy-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-files" viewBox="0 0 16 16" part="svg">
<path d="M13 0H6a2 2 0 0 0-2 2 2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h7a2 2 0 0 0 2-2 2 2 0 0 0 2-2V2a2 2 0 0 0-2-2zm0 13V4a2 2 0 0 0-2-2H5a1 1 0 0 1 1-1h7a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1zM3 4a1 1 0 0 1 1-1h7a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4z"></path>
</svg>
<svg class="copy-code-button__copied-icon" style="display: none;" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-check-lg" viewBox="0 0 16 16" part="svg">
<path d="M12.736 3.97a.733.733 0 0 1 1.047 0c.286.289.29.756.01 1.05L7.88 12.01a.733.733 0 0 1-1.065.02L3.217 8.384a.757.757 0 0 1 0-1.06.733.733 0 0 1 1.047 0l3.052 3.093 5.4-6.425a.247.247 0 0 1 .02-.022Z"></path>
</svg>
`;
pre.append(button);
});
return doc;
};

41
docs/_utilities/external-links.cjs Normal file
View File

@@ -0,0 +1,41 @@
const { isExternalLink } = require('./strings.cjs');
/**
* Transforms external links to make them safer and optionally add a target. The provided doc should be a document
* object provided by JSDOM. The same document will be returned with the appropriate DOM manipulations.
*/
module.exports = function (doc, options) {
options = {
className: 'external-link', // the class name to add to links
noopener: true, // sets rel="noopener"
noreferrer: true, // sets rel="noreferrer"
ignore: link => false, // callback function to filter links that should be ignored
within: 'body', // element that contains the target links
target: '', // sets the target attribute
...options
};
const within = doc.querySelector(options.within);
if (within) {
within.querySelectorAll('a').forEach(link => {
if (isExternalLink(link) && !options.ignore(link)) {
link.classList.add(options.className);
const rel = [];
if (options.noopener) rel.push('noopener');
if (options.noreferrer) rel.push('noreferrer');
if (rel.length) {
link.setAttribute('rel', rel.join(' '));
}
if (options.target) {
link.setAttribute('target', options.target);
}
}
});
}
return doc;
};

63
docs/_utilities/highlight-code.cjs Normal file
View File

@@ -0,0 +1,63 @@
const Prism = require('prismjs');
const PrismLoader = require('prismjs/components/index.js');
PrismLoader('diff');
PrismLoader.silent = true;
/** Highlights a code string. */
function highlight(code, language) {
const alias = language.replace(/^diff-/, '');
const isDiff = /^diff-/i.test(language);
// Auto-load the target language
if (!Prism.languages[alias]) {
PrismLoader(alias);
if (!Prism.languages[alias]) {
throw new Error(`Unsupported language for code highlighting: "${language}"`);
}
}
// Register diff-* languages to use the diff grammar
if (isDiff) {
Prism.languages[language] = Prism.languages.diff;
}
return Prism.highlight(code, Prism.languages[language], language);
}
/**
* Highlights all code fields that have a language parameter. If the language has a colon in its name, the first chunk
* will be the language used and additional chunks will be applied as classes to the `<pre>`. For example, a code field
* tagged with "html:preview" will be rendered as `<pre class="language-html preview">`.
*
* The provided doc should be a document object provided by JSDOM. The same document will be returned with the
* appropriate DOM manipulations.
*/
module.exports = function (doc) {
doc.querySelectorAll('pre > code[class]').forEach(code => {
// Look for class="language-*" and split colons into separate classes
code.classList.forEach(className => {
if (className.startsWith('language-')) {
//
// We use certain suffixes to indicate code previews, expanded states, etc. The class might look something like
// this:
//
// class="language-html:preview:expanded"
//
// The language will always come first, so we need to drop the "language-" prefix and everything after the first
// color to get the highlighter language.
//
const language = className.replace(/^language-/, '').split(':')[0];
try {
code.innerHTML = highlight(code.textContent ?? '', language);
} catch (err) {
// Language not found, skip it
}
}
});
});
return doc;
};

67
docs/_utilities/markdown.cjs Normal file
View File

@@ -0,0 +1,67 @@
const MarkdownIt = require('markdown-it');
const markdownItContainer = require('markdown-it-container');
const markdownItIns = require('markdown-it-ins');
const markdownItKbd = require('markdown-it-kbd');
const markdownItMark = require('markdown-it-mark');
const markdownItReplaceIt = require('markdown-it-replace-it');
const markdown = MarkdownIt({
html: true,
xhtmlOut: false,
breaks: false,
langPrefix: 'language-',
linkify: false,
typographer: false
});
// Third-party plugins
markdown.use(markdownItContainer);
markdown.use(markdownItIns);
markdown.use(markdownItKbd);
markdown.use(markdownItMark);
markdown.use(markdownItReplaceIt);
// Callouts
['tip', 'warning', 'danger'].forEach(type => {
markdown.use(markdownItContainer, type, {
render: function (tokens, idx) {
if (tokens[idx].nesting === 1) {
return `<div role="alert" class="callout callout--${type}">`;
}
return '</div>\n';
}
});
});
// Asides
markdown.use(markdownItContainer, 'aside', {
render: function (tokens, idx) {
if (tokens[idx].nesting === 1) {
return `<aside>`;
}
return '</aside>\n';
}
});
// Details
markdown.use(markdownItContainer, 'details', {
validate: params => params.trim().match(/^details\s+(.*)$/),
render: (tokens, idx) => {
const m = tokens[idx].info.trim().match(/^details\s+(.*)$/);
if (tokens[idx].nesting === 1) {
return `<details>\n<summary><span>${markdown.utils.escapeHtml(m[1])}</span></summary>\n`;
}
return '</details>\n';
}
});
// Replace [#1234] with a link to GitHub issues
markdownItReplaceIt.replacements.push({
name: 'github-issues',
re: /\[#([0-9]+)\]/gs,
sub: '<a href="https://github.com/shoelace-style/shoelace/issues/$1">#$1</a>',
html: true,
default: true
});
module.exports = markdown;

26
docs/_utilities/prettier.cjs Normal file
View File

@@ -0,0 +1,26 @@
const { format } = require('prettier');
/** Formats markup using prettier. */
module.exports = function (content, options) {
options = {
arrowParens: 'avoid',
bracketSpacing: true,
htmlWhitespaceSensitivity: 'css',
insertPragma: false,
bracketSameLine: false,
jsxSingleQuote: false,
parser: 'html',
printWidth: 120,
proseWrap: 'preserve',
quoteProps: 'as-needed',
requirePragma: false,
semi: true,
singleQuote: true,
tabWidth: 2,
trailingComma: 'none',
useTabs: false,
...options
};
return format(content, options);
}

21
docs/_utilities/scrolling-tables.cjs Normal file
View File

@@ -0,0 +1,21 @@
/**
* Turns headings into clickable, deep linkable anchors. The provided doc should be a document object provided by JSDOM.
* The same document will be returned with the appropriate DOM manipulations.
*/
module.exports = function (doc, options) {
const tables = [...doc.querySelectorAll('table')];
options = {
className: 'table-scroll', // the class name to add to the table's container
...options
};
tables.forEach(table => {
const div = doc.createElement('div');
div.classList.add(options.className);
table.insertAdjacentElement('beforebegin', div);
div.append(table);
});
return doc;
};

16
docs/_utilities/strings.cjs Normal file
View File

@@ -0,0 +1,16 @@
const slugify = require('slugify');
/** Creates a slug from an arbitrary string of text. */
module.exports.createSlug = function (text) {
return slugify(String(text), {
remove: /[^\w|\s]/g,
lower: true
});
};
/** Determines whether or not a link is external. */
module.exports.isExternalLink = function (link) {
// We use the "internal" hostname when initializing JSDOM so we know that those are local links
if (!link.hostname || link.hostname === 'internal') return false;
return true;
};

42
docs/_utilities/table-of-contents.cjs Normal file
View File

@@ -0,0 +1,42 @@
/**
* Generates an in-page table of contents based on headings.
*/
module.exports = function (doc, options) {
options = {
levels: ['h2'], // headings to include (they must have an id)
container: 'nav', // the container to append links to
listItem: true, // if true, links will be wrapped in <li>
within: 'body', // the element containing the headings to summarize
...options
};
const container = doc.querySelector(options.container);
const within = doc.querySelector(options.within);
const headingSelector = options.levels.map(h => `${h}[id]`).join(', ');
if (!container || !within) {
return doc;
}
within.querySelectorAll(headingSelector).forEach(heading => {
const listItem = doc.createElement('li');
const link = doc.createElement('a');
const level = heading.tagName.slice(1);
link.href = `#${heading.id}`;
link.textContent = heading.textContent;
if (options.listItem) {
// List item + link
listItem.setAttribute('data-level', level);
listItem.append(link);
container.append(listItem);
} else {
// Link only
link.setAttribute('data-level', level);
container.append(link);
}
});
return doc;
};

23
docs/_utilities/typography.cjs Normal file
View File

@@ -0,0 +1,23 @@
const smartquotes = require('smartquotes');
smartquotes.replacements.push([/\-\-\-/g, '\u2014']); // em dash
smartquotes.replacements.push([/\-\-/g, '\u2013']); // en dash
smartquotes.replacements.push([/\.\.\./g, '\u2026']); // ellipsis
smartquotes.replacements.push([/\(c\)/gi, '\u00A9']); // copyright
smartquotes.replacements.push([/\(r\)/gi, '\u00AE']); // registered trademark
smartquotes.replacements.push([/\?!/g, '\u2048']); // ?!
smartquotes.replacements.push([/!!/g, '\u203C']); // !!
smartquotes.replacements.push([/\?\?/g, '\u2047']); // ??
smartquotes.replacements.push([/([0-9]\s?)\-(\s?[0-9])/g, '$1\u2013$2']); // number ranges use en dash
/**
* Improves typography by adding smart quotes and similar corrections within the specified element(s).
*
* The provided doc should be a document object provided by JSDOM. The same document will be returned with the
* appropriate DOM manipulations.
*/
module.exports = function (doc, selector = 'body') {
const elements = [...doc.querySelectorAll(selector)];
elements.forEach(el => smartquotes.element(el));
return doc;
};

1
docs/assets/icons/sprite.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 1.0 MiB

23
docs/assets/images/gitpod.svg Normal file
View File

@@ -0,0 +1,23 @@
<svg width="160" height="45" fill="none" xmlns="http://www.w3.org/2000/svg">
<g filter="url(#filter0_d)">
<rect x="2" y="2" width="156" height="40" rx="16" fill="#F9F9F9"/>
<path fill-rule="evenodd" clip-rule="evenodd" d="M30.425 11.174c.604 1.114.233 2.53-.83 3.164l-6.986 4.166a.378.378 0 00-.18.325v6.748c0 .134.069.258.18.325l5.714 3.407c.11.066.244.066.354 0l5.714-3.407a.378.378 0 00.18-.325V21.29l-4.986 2.936c-1.067.628-2.416.231-3.015-.886-.6-1.118-.22-2.532.846-3.16l7.008-4.127c2.048-1.206 4.576.345 4.576 2.806v6.718c0 1.803-.924 3.467-2.42 4.36l-5.713 3.407a4.596 4.596 0 01-4.734 0l-5.714-3.408C18.924 29.044 18 27.38 18 25.576V18.83c0-1.803.924-3.467 2.42-4.36l6.985-4.165c1.063-.634 2.415-.245 3.02.87z" fill="url(#paint0_linear)"/>
<path fill="#F9F9F9" d="M47 12.5h95v-1H47z"/>
<path d="M52.538 27.752c2.744 0 4.844-1.876 4.844-5.152 0-3.108-2.1-5.152-4.844-5.152s-4.802 2.002-4.802 5.152c0 3.29 2.058 5.152 4.802 5.152zm0-1.554c-1.736 0-2.912-1.316-2.912-3.598 0-2.226 1.162-3.598 2.912-3.598s2.954 1.4 2.954 3.598c0 2.31-1.218 3.598-2.954 3.598zm7.89 4.158V27.22c0-.196-.013-.378-.055-.658.434.7 1.022 1.19 2.17 1.19 1.736 0 3.066-1.414 3.066-3.626 0-2.17-1.19-3.682-2.996-3.682-1.078 0-1.806.476-2.24 1.204.042-.28.056-.462.056-.672v-.308H58.72v9.688h1.708zm1.695-3.948c-1.036 0-1.764-.938-1.764-2.31 0-1.414.742-2.296 1.764-2.296 1.092 0 1.75.952 1.75 2.296 0 1.372-.7 2.31-1.75 2.31zm7.866 1.344c1.848 0 3.052-1.078 3.192-2.478h-1.736c-.112.714-.714 1.134-1.456 1.134-1.036 0-1.722-.826-1.736-1.904h4.97v-.378c0-2.226-1.204-3.682-3.29-3.682-1.988 0-3.43 1.47-3.43 3.626 0 2.366 1.442 3.682 3.486 3.682zm-1.75-4.48c.098-.896.756-1.554 1.68-1.554.924 0 1.526.63 1.554 1.554H68.24zm8.006 4.228v-4.004c0-.952.616-1.694 1.456-1.694.798 0 1.288.63 1.288 1.638v4.06h1.708v-4.312c0-1.68-.896-2.744-2.408-2.744-1.078 0-1.722.518-2.1 1.204.042-.266.056-.476.056-.672v-.308h-1.708V27.5h1.708zm8.911-7.868h1.792V17.84h-1.792v1.792zm.042 1.036V27.5h1.708v-6.832h-1.708zm5.097 6.832v-4.004c0-.952.616-1.694 1.456-1.694.798 0 1.288.63 1.288 1.638v4.06h1.708v-4.312c0-1.68-.896-2.744-2.408-2.744-1.078 0-1.722.518-2.1 1.204.042-.266.056-.476.056-.672v-.308h-1.708V27.5h1.708zm13.238.252c1.526 0 2.52-.658 2.982-1.54-.07.322-.098.644-.098.98v.308h1.68v-5.222h-4.34v1.554h2.66v.07c0 1.4-1.134 2.296-2.59 2.296-1.792 0-3.024-1.372-3.024-3.598s1.26-3.598 3.066-3.598c1.302 0 2.17.756 2.296 1.736h1.89c-.182-1.904-1.764-3.29-4.214-3.29-2.954 0-4.928 2.128-4.928 5.152 0 3.136 1.848 5.152 4.62 5.152zm6.063-8.12h1.792V17.84h-1.792v1.792zm.042 1.036V27.5h1.708v-6.832h-1.708zm6.413 6.958c.434 0 .84-.07 1.008-.126v-1.288c-.168.028-.35.042-.518.042-.728 0-1.008-.42-1.008-1.134v-3.094h1.68v-1.358h-1.68v-2.464h-1.708v2.464h-1.554v1.358h1.554v3.346c0 1.526.77 2.254 2.226 2.254zm3.961 2.73V27.22c0-.196-.014-.378-.056-.658.434.7 1.022 1.19 2.17 1.19 1.736 0 3.066-1.414 3.066-3.626 0-2.17-1.19-3.682-2.996-3.682-1.078 0-1.806.476-2.24 1.204.042-.28.056-.462.056-.672v-.308h-1.708v9.688h1.708zm1.694-3.948c-1.036 0-1.764-.938-1.764-2.31 0-1.414.742-2.296 1.764-2.296 1.092 0 1.75.952 1.75 2.296 0 1.372-.7 2.31-1.75 2.31zm7.88 1.344c2.058 0 3.514-1.372 3.514-3.64 0-2.24-1.456-3.668-3.514-3.668-2.044 0-3.5 1.428-3.5 3.668 0 2.268 1.442 3.64 3.5 3.64zm0-1.344c-1.064 0-1.764-.84-1.764-2.296 0-1.484.728-2.31 1.764-2.31 1.05 0 1.778.826 1.778 2.31 0 1.456-.714 2.296-1.778 2.296zm7.551 1.344c1.26 0 1.876-.686 2.142-1.19-.056.238-.056.42-.056.658v.28h1.708v-9.8h-1.708v3.276c0 .21 0 .42.056.672-.392-.658-1.05-1.204-2.114-1.204-1.596 0-3.15 1.218-3.15 3.668 0 2.408 1.316 3.64 3.122 3.64zm.406-1.344c-1.022 0-1.792-.896-1.792-2.31 0-1.358.77-2.296 1.792-2.296s1.778.896 1.778 2.296c0 1.372-.756 2.31-1.778 2.31z" fill="#12100C"/>
</g>
<defs>
<linearGradient id="paint0_linear" x1="33.806" y1="13.629" x2="22.389" y2="30.86" gradientUnits="userSpaceOnUse">
<stop stop-color="#FFB45B"/>
<stop offset="1" stop-color="#FF8A00"/>
</linearGradient>
<filter id="filter0_d" x="0" y=".5" width="160" height="44" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feFlood flood-opacity="0" result="BackgroundImageFix"/>
<feColorMatrix in="SourceAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/>
<feOffset dy=".5"/>
<feGaussianBlur stdDeviation="1"/>
<feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"/>
<feBlend in2="BackgroundImageFix" result="effect1_dropShadow"/>
<feBlend in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
</filter>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.5 KiB

32
docs/assets/images/undraw-taken.svg Normal file
View File

@@ -0,0 +1,32 @@
<svg width="673" height="739" viewBox="0 0 673 739" xmlns="http://www.w3.org/2000/svg">
<g fill-rule="nonzero" fill="none">
<path d="M467 149.805c-46.62-7.44-99.71-11.41-155-11.41-50.6 0-99.35 3.32-142.98 9.58.01-.67.02-1.34.05-2.01C171.475 65.082 237.996.903 318.914 1.398c80.917.494 146.649 65.48 148.066 146.387.01.68.02 1.35.02 2.02Z" fill="#0BA5E9"/>
<path d="M337.55 1.342a149.047 149.047 0 0 0-168.93 143.229c-.031.67-.04 1.34-.05 2.01 12.961-1.86 26.384-3.454 40.164-4.784 3.478-71.745 57.64-130.8 128.816-140.455Z" opacity=".1" fill="#FFF"/>
<path d="M532.18 161.625a600.121 600.121 0 0 0-65.2-13.84 943.364 943.364 0 0 0-108.74-10.45 1133.608 1133.608 0 0 0-83.01-.34 973.29 973.29 0 0 0-106.16 8.97 624.292 624.292 0 0 0-77.25 15.66C32.61 177.995 0 199.935 0 223.395s32.61 45.4 91.82 61.77c41.64 11.52 92.98 19.37 148.92 22.97 23.09 1.5 46.96 2.26 71.26 2.26 24.38 0 48.33-.77 71.49-2.27 50.91-3.29 98.01-10.1 137.43-20 .21-.06.41-.11.62-.16 2.66-.66 5.28-1.35 7.87-2.04.93-.26 1.85-.51 2.77-.76a.978.978 0 0 1 .16-.05c.88-.24 1.75-.49 2.62-.73 1.74-.5 3.46-.99 5.15-1.5.08-.02.15-.04.22-.06 1.47-.44 2.91-.88 4.34-1.32 1.17-.37 2.33-.73 3.48-1.1.84-.27 1.67-.54 2.49-.81.6-.2 1.19-.39 1.77-.59.79-.26 1.58-.53 2.36-.8.33-.11.66-.22.98-.34.75-.25 1.48-.51 2.21-.77.79-.28 1.58-.57 2.36-.85.65-.23 1.3-.47 1.94-.71.54-.21 1.07-.41 1.61-.61 1.47-.55 2.91-1.12 4.33-1.68.71-.29 1.42-.57 2.12-.86.69-.28 1.39-.57 2.07-.86 1.12-.47 2.22-.94 3.3-1.41.52-.24 1.05-.47 1.56-.69.39-.18.77-.35 1.16-.53.28-.12.56-.25.83-.38 1.01-.46 2.01-.93 2.99-1.4 3.76-1.8 7.27-3.64 10.53-5.52 20.45-11.71 31.24-24.7 31.24-38.2 0-23.46-32.61-45.4-91.82-61.77Zm-.54 121.62c-41.69 11.53-93.17 19.38-149.26 22.95-22.81 1.45-46.39 2.2-70.38 2.2-23.91 0-47.41-.74-70.15-2.19-56.18-3.56-107.74-11.41-149.49-22.96C34.09 267.125 2 245.875 2 223.395c0-1.986.252-3.965.74-5.89 5.1-20.28 36.47-39.26 89.62-53.96a623.806 623.806 0 0 1 76.66-15.57 976.027 976.027 0 0 1 106.8-9c11.92-.39 23.98-.583 36.18-.58 15.41 0 30.65.31 45.63.91a941.367 941.367 0 0 1 109.37 10.5 598.858 598.858 0 0 1 64.64 13.74c53.14 14.7 84.5 33.67 89.61 53.94.496 1.93.75 3.916.75 5.91 0 22.48-32.09 43.73-90.36 59.85Z" fill="#3F3D56"/>
<path d="M623.43 224.305c0 13.36-11.01 26-30.67 37.29-3.27 1.88-6.79 3.72-10.53 5.52-.98.47-1.98.94-2.99 1.4-.27.13-.55.26-.83.38-.39.18-.77.35-1.16.53-.51.22-1.04.45-1.56.69-1.08.47-2.18.94-3.3 1.41-.68.29-1.38.58-2.07.86-.7.29-1.41.57-2.12.86-1.42.56-2.86 1.13-4.33 1.68-.54.2-1.07.4-1.61.61-.64.24-1.29.48-1.94.71-.78.28-1.57.57-2.36.85-.73.26-1.46.52-2.21.77-.32.12-.65.23-.98.34-.78.27-1.57.54-2.36.8-.58.2-1.17.39-1.77.59-.82.27-1.65.54-2.49.81-1.15.37-2.31.73-3.48 1.1-1.43.44-2.87.88-4.34 1.32-.07.02-.14.04-.22.06-1.69.51-3.41 1-5.15 1.5-.87.24-1.74.49-2.62.73a.978.978 0 0 0-.16.05c-.92.25-1.84.5-2.77.76-2.58.68-5.21 1.37-7.87 2.04-.21.05-.41.1-.62.16-38.35 9.58-85.4 16.56-137.47 19.93-22.81 1.47-46.59 2.25-71.02 2.25-24.65 0-48.63-.79-71.62-2.29-137.24-8.95-239.38-43.03-239.38-83.71.01-2.475.388-4.936 1.12-7.3.06.17.12.33.19.5 14.27 37.48 115.54 67.77 246.94 75.16 20.13 1.14 40.98 1.73 62.32 1.73 21.43 0 42.36-.6 62.57-1.74 131.29-7.42 232.46-37.72 246.68-75.17.24-.6.45-1.2.63-1.8a25.304 25.304 0 0 1 1.55 8.62ZM91.67 213.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217Z" fill="#3F3D56"/>
<path d="M162.67 260.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217ZM531.67 213.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217ZM460.67 260.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217ZM311.67 282.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217Z" fill="#3F3D56"/>
<circle fill="#2F2E41" cx="336.978" cy="450.705" r="42.012"/>
<path fill="#2F2E41" d="m300.555 488.547 20.447-10.24 5.715 11.413-20.447 10.24z"/>
<ellipse fill="#2F2E41" transform="rotate(-56.601 300.086 492.946)" cx="300.086" cy="492.946" rx="3.989" ry="10.636"/>
<path fill="#2F2E41" d="m347.239 489.72 5.715-11.412 20.447 10.24-5.715 11.412z"/>
<ellipse fill="#2F2E41" transform="rotate(-33.399 373.87 492.946)" cx="373.87" cy="492.946" rx="10.636" ry="3.989"/>
<circle fill="#FFF" cx="334.037" cy="440.429" r="14.359"/>
<ellipse fill="#3F3D56" transform="rotate(-45 334.135 434.282)" cx="334.135" cy="434.282" rx="4.766" ry="4.8"/>
<path d="M370.12 405c.632-15.553-12.773-28.727-29.941-29.425-17.168-.697-31.597 11.346-32.229 26.9-.632 15.553 11.302 19.087 28.47 19.785 17.167.697 33.068-1.706 33.7-17.26Z" fill="#0BA5E9"/>
<ellipse fill="#2F2E41" transform="rotate(-40.645 380.654 456.766)" cx="380.654" cy="456.766" rx="6.594" ry="21.006"/>
<ellipse fill="#2F2E41" transform="rotate(-49.355 293.42 456.766)" cx="293.419" cy="456.766" rx="21.006" ry="6.594"/>
<path d="M348.517 467.262a9.572 9.572 0 1 1-18.836 3.428l-.003-.018c-.942-5.202 3.08-7.043 8.282-7.985 5.203-.942 9.615-.628 10.557 4.575Z" fill="#FFF"/>
<path d="M266 495.395a2 2 0 0 1-2-2v-118a2 2 0 0 1 4 0v118a2 2 0 0 1-2 2ZM236 601.395a2 2 0 0 1-2-2v-86a2 2 0 0 1 4 0v86a2 2 0 0 1-2 2ZM313 530.395a2 2 0 0 1-2-2v-118a2 2 0 0 1 4 0v118a2 2 0 0 1-2 2ZM284 615.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM325 369.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM225 390.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM399 395.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM395 545.395a2 2 0 0 1-2-2v-58a2 2 0 0 1 4 0v58a2 2 0 0 1-2 2ZM355 596.395a2 2 0 0 1-2-2v-86a2 2 0 0 1 4 0v86a2 2 0 0 1-2 2ZM363 449.395a2 2 0 0 1-2-2v-118a2 2 0 0 1 4 0v118a2 2 0 0 1-2 2Z" fill="#CCC"/>
<ellipse fill="#2F2E41" transform="rotate(-39.938 594.37 683.981)" cx="594.369" cy="683.981" rx="6.76" ry="21.534"/>
<circle fill="#2F2E41" transform="rotate(-71.565 548.562 676.503)" cx="548.562" cy="676.503" r="43.067"/>
<path fill="#2F2E41" d="M553.707 710.303h13.084v23.442h-13.084zM527.54 710.303h13.084v23.442H527.54z"/>
<ellipse fill="#2F2E41" cx="555.888" cy="734.017" rx="10.903" ry="4.089"/>
<ellipse fill="#2F2E41" cx="529.72" cy="733.472" rx="10.903" ry="4.089"/>
<path d="M535.04 622.366c3.845-15.487 20.82-24.6 37.914-20.356 17.094 4.245 27.834 20.24 23.989 35.727-3.846 15.487-16.604 15.537-33.698 11.293-17.094-4.245-32.051-11.177-28.206-26.664Z" fill="#0BA5E9"/>
<ellipse fill="#2F2E41" transform="rotate(-64.626 500.054 656.52)" cx="500.054" cy="656.52" rx="6.76" ry="21.534"/>
<circle fill="#FFF" cx="542.124" cy="667.416" r="14.359"/>
<circle fill="#3F3D56" cx="536.222" cy="662.269" r="4.786"/>
<circle fill="#FFF" cx="542" cy="697.395" r="6"/>
<path d="M671.531 738.395h-236a1 1 0 1 1 0-2h236a1 1 0 0 1 0 2Z" fill="#3F3D56"/>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.6 KiB

247
docs/assets/scripts/code-previews.js Normal file
View File

@@ -0,0 +1,247 @@
(() => {
function convertModuleLinks(html) {
html = html
.replace(/@shoelace-style\/shoelace/g, `https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}`)
.replace(/from 'react'/g, `from 'https://cdn.skypack.dev/react@${reactVersion}'`)
.replace(/from "react"/g, `from "https://cdn.skypack.dev/react@${reactVersion}"`);
return html;
}
function getAdjacentExample(name, pre) {
let currentPre = pre.nextElementSibling;
while (currentPre?.tagName.toLowerCase() === 'pre') {
if (currentPre?.getAttribute('data-lang').split(' ').includes(name)) {
return currentPre;
}
currentPre = currentPre.nextElementSibling;
}
return null;
}
function runScript(script) {
const newScript = document.createElement('script');
if (script.type === 'module') {
newScript.type = 'module';
newScript.textContent = script.innerHTML;
} else {
newScript.appendChild(document.createTextNode(`(() => { ${script.innerHTML} })();`));
}
script.parentNode.replaceChild(newScript, script);
}
function getFlavor() {
return sessionStorage.getItem('flavor') || 'html';
}
function setFlavor(newFlavor) {
flavor = ['html', 'react'].includes(newFlavor) ? newFlavor : 'html';
sessionStorage.setItem('flavor', flavor);
// Set the flavor class on the body
document.documentElement.classList.toggle('flavor-html', flavor === 'html');
document.documentElement.classList.toggle('flavor-react', flavor === 'react');
}
const shoelaceVersion = document.documentElement.getAttribute('data-shoelace-version');
const reactVersion = '18.2.0';
let flavor = getFlavor();
let count = 1;
// We need the version to open
if (!shoelaceVersion) {
throw new Error('The data-shoelace-version attribute is missing from <html>.');
}
// Sync flavor UI on page load
setFlavor(getFlavor());
document.querySelectorAll('.code-preview__button--html').forEach(preview => {
if (flavor === 'html') {
preview.classList.add('code-preview__button--selected');
}
});
document.querySelectorAll('.code-preview__button--react').forEach(preview => {
if (flavor === 'react') {
preview.classList.add('code-preview__button--selected');
}
});
//
// Resizing previews
//
[...document.querySelectorAll('.code-preview__preview')].forEach(preview => {
const resizer = preview.querySelector('.code-preview__resizer');
let startX;
let startWidth;
function dragStart(event) {
startX = event.changedTouches ? event.changedTouches[0].pageX : event.clientX;
startWidth = parseInt(document.defaultView.getComputedStyle(preview).width, 10);
preview.classList.add('code-preview__preview--dragging');
event.preventDefault();
document.documentElement.addEventListener('mousemove', dragMove);
document.documentElement.addEventListener('touchmove', dragMove);
document.documentElement.addEventListener('mouseup', dragStop);
document.documentElement.addEventListener('touchend', dragStop);
}
function dragMove(event) {
setWidth(startWidth + (event.changedTouches ? event.changedTouches[0].pageX : event.pageX) - startX);
}
function dragStop() {
preview.classList.remove('code-preview__preview--dragging');
document.documentElement.removeEventListener('mousemove', dragMove);
document.documentElement.removeEventListener('touchmove', dragMove);
document.documentElement.removeEventListener('mouseup', dragStop);
document.documentElement.removeEventListener('touchend', dragStop);
}
function setWidth(width) {
preview.style.width = `${width}px`;
}
resizer.addEventListener('mousedown', dragStart);
resizer.addEventListener('touchstart', dragStart, { passive: true });
}, false);
//
// Toggle source mode
//
document.addEventListener('click', event => {
const button = event.target.closest('.code-preview__button');
const codeBlock = button?.closest('.code-preview');
if (button?.classList.contains('code-preview__button--html')) {
// Show HTML
setFlavor('html');
toggleSource(codeBlock, true);
} else if (button?.classList.contains('code-preview__button--react')) {
// Show React
setFlavor('react');
toggleSource(codeBlock, true);
} else if (button?.classList.contains('code-preview__toggle')) {
// Toggle source
toggleSource(codeBlock);
} else {
return;
}
// Update flavor buttons
[...document.querySelectorAll('.code-preview')].forEach(cb => {
cb.querySelector('.code-preview__button--html')?.classList.toggle(
'code-preview__button--selected',
flavor === 'html'
);
cb.querySelector('.code-preview__button--react')?.classList.toggle(
'code-preview__button--selected',
flavor === 'react'
);
});
});
function toggleSource(codeBlock, force) {
const toggle = codeBlock.querySelector('.code-preview__toggle');
if (toggle) {
codeBlock.classList.toggle('code-preview--expanded', force === undefined ? undefined : force);
event.target.setAttribute('aria-expanded', codeBlock.classList.contains('code-preview--expanded'));
}
}
//
// Open in CodePen
//
document.addEventListener('click', event => {
const button = event.target.closest('button');
if (button?.classList.contains('code-preview__button--codepen')) {
const codeBlock = button.closest('.code-preview');
const htmlExample = codeBlock.querySelector('.code-preview__source--html > pre > code')?.textContent;
const reactExample = codeBlock.querySelector('.code-preview__source--react > pre > code')?.textContent;
const isReact = flavor === 'react' && typeof reactExample === 'string';
const theme = document.documentElement.classList.contains('sl-theme-dark') ? 'dark' : 'light';
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const isDark = theme === 'dark' || (theme === 'auto' && prefersDark);
const editors = isReact ? '0010' : '1000';
let htmlTemplate = '';
let jsTemplate = '';
let cssTemplate = '';
const form = document.createElement('form');
form.action = 'https://codepen.io/pen/define';
form.method = 'POST';
form.target = '_blank';
// HTML templates
if (!isReact) {
htmlTemplate =
`<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/dist/shoelace.js"></script>\n` +
`\n${htmlExample}`;
jsTemplate = '';
}
// React templates
if (isReact) {
htmlTemplate = '<div id="root"></div>';
jsTemplate =
`import React from 'https://cdn.skypack.dev/react@${reactVersion}';\n` +
`import ReactDOM from 'https://cdn.skypack.dev/react-dom@${reactVersion}';\n` +
`import { setBasePath } from 'https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}/dist/utilities/base-path';\n` +
`\n` +
`// Set the base path for Shoelace assets\n` +
`setBasePath('https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}/dist/')\n` +
`\n${convertModuleLinks(reactExample)}\n` +
`\n` +
`ReactDOM.render(<App />, document.getElementById('root'));`;
}
// CSS templates
cssTemplate =
`@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/dist/themes/${
isDark ? 'dark' : 'light'
}.css';\n` +
'\n' +
'body {\n' +
' font: 16px sans-serif;\n' +
' background-color: var(--sl-color-neutral-0);\n' +
' color: var(--sl-color-neutral-900);\n' +
' padding: 1rem;\n' +
'}';
// Docs: https://blog.codepen.io/documentation/prefill/
const data = {
title: '',
description: '',
tags: ['shoelace', 'web components'],
editors,
head: `<meta name="viewport" content="width=device-width">`,
html_classes: `sl-theme-${isDark ? 'dark' : 'light'}`,
css_external: ``,
js_external: ``,
js_module: true,
js_pre_processor: isReact ? 'babel' : 'none',
html: htmlTemplate,
css: cssTemplate,
js: jsTemplate
};
const input = document.createElement('input');
input.type = 'hidden';
input.name = 'data';
input.value = JSON.stringify(data);
form.append(input);
document.documentElement.append(form);
form.submit();
form.remove();
}
});
})();

216
docs/assets/scripts/docs.js Normal file
View File

@@ -0,0 +1,216 @@
//
// Sidebar
//
// When the sidebar is hidden, we apply the inert attribute to prevent focus from reaching it. Due to the many states
// the sidebar can have (e.g. static, hidden, expanded), we test for visibility by checking to see if it's placed
// offscreen or not. Then, on resize/transition we make sure to update the attribute accordingly.
//
(() => {
function isSidebarOpen() {
return document.documentElement.classList.contains('sidebar-open');
}
function isSidebarVisible() {
return sidebar.getBoundingClientRect().x >= 0;
}
function toggleSidebar(force) {
const isOpen = typeof force === 'boolean' ? force : !isSidebarOpen();
return document.documentElement.classList.toggle('sidebar-open', isOpen);
}
function updateInert() {
sidebar.inert = !isSidebarVisible();
}
const menuToggle = document.getElementById('menu-toggle');
const sidebar = document.getElementById('sidebar');
// Toggle the menu
if (menuToggle) {
menuToggle.addEventListener('click', toggleSidebar);
}
// Update the sidebar's inert state when the window resizes and when the sidebar transitions
window.addEventListener('resize', () => toggleSidebar(false));
sidebar.addEventListener('transitionend', updateInert);
// Close when open and escape is pressed
document.addEventListener('keydown', event => {
if (event.key === 'Escape' && isSidebarOpen()) {
event.stopImmediatePropagation();
toggleSidebar();
}
});
// Close when clicking outside of the sidebar
document.addEventListener('mousedown', event => {
if (isSidebarOpen() & !event.target.closest('#sidebar, #menu-toggle')) {
event.stopImmediatePropagation();
toggleSidebar();
}
});
updateInert();
})();
//
// Theme switcher
//
(() => {
function toggleTheme() {
const isDark = !document.documentElement.classList.contains('sl-theme-dark');
document.documentElement.classList.toggle('sl-theme-dark', isDark);
localStorage.setItem('theme', isDark ? 'dark' : 'light');
}
// Toggle the theme
const themeToggle = document.getElementById('theme-toggle');
if (themeToggle) {
themeToggle.addEventListener('click', toggleTheme);
}
// Toggle with backslash
document.addEventListener('keydown', event => {
if (
event.key === '\\' &&
!event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
) {
event.preventDefault();
toggleTheme();
}
});
})();
//
// Open details when printing
//
(() => {
const detailsOpenOnPrint = new Set();
window.addEventListener('beforeprint', () => {
detailsOpenOnPrint.clear();
document.querySelectorAll('details').forEach(details => {
if (details.open) {
detailsOpenOnPrint.add(details);
}
details.open = true;
});
});
window.addEventListener('afterprint', () => {
document.querySelectorAll('details').forEach(details => {
details.open = detailsOpenOnPrint.has(details);
});
detailsOpenOnPrint.clear();
});
})();
//
// Copy code buttons
//
(() => {
document.addEventListener('click', event => {
const button = event.target.closest('.copy-code-button');
const pre = button?.closest('pre');
const code = pre?.querySelector('code');
const copyIcon = button?.querySelector('.copy-code-button__copy-icon');
const copiedIcon = button?.querySelector('.copy-code-button__copied-icon');
if (button && code) {
navigator.clipboard.writeText(code.innerText);
copyIcon.style.display = 'none';
copiedIcon.style.display = 'inline';
button.classList.add('copy-code-button--copied');
setTimeout(() => {
copyIcon.style.display = 'inline';
copiedIcon.style.display = 'none';
button.classList.remove('copy-code-button--copied');
}, 1000);
}
});
})();
//
// Smooth links
//
(() => {
document.addEventListener('click', event => {
const link = event.target.closest('a');
const id = (link?.hash ?? '').substr(1);
const isFragment = link?.hasAttribute('href') && link?.getAttribute('href').startsWith('#');
if (!link || !isFragment || link.getAttribute('data-smooth-link') === 'false') {
return;
}
// Scroll to the top
if (link.hash === '') {
event.preventDefault();
window.scroll({ top: 0, behavior: 'smooth' });
history.pushState(undefined, undefined, location.pathname);
}
// Scroll to an id
if (id) {
const target = document.getElementById(id);
if (target) {
event.preventDefault();
window.scroll({ top: target.offsetTop, behavior: 'smooth' });
history.pushState(undefined, undefined, `#${id}`);
}
}
});
})();
//
// Table of Contents scrollspy
//
(() => {
const links = [...document.querySelectorAll('.content__toc a')];
const linkTargets = new WeakMap();
const visibleTargets = new WeakSet();
const observer = new IntersectionObserver(handleIntersect, { rootMargin: '0px 0px' });
let debounce;
function handleIntersect(entries) {
entries.forEach(entry => {
// Remember which targets are visible
if (entry.isIntersecting) {
visibleTargets.add(entry.target);
} else {
visibleTargets.delete(entry.target);
}
});
updateActiveLinks();
}
function updateActiveLinks() {
// Find the first visible target and activate the respective link
links.find(link => {
const target = linkTargets.get(link);
if (target && visibleTargets.has(target)) {
links.forEach(el => el.classList.toggle('active', el === link));
return true;
}
return false;
});
}
// Observe link targets
links.forEach(link => {
const hash = link.hash.slice(1);
const target = hash ? document.querySelector(`.content__body #${hash}`) : null;
if (target) {
linkTargets.set(link, target);
observer.observe(target);
}
});
})();

369
docs/assets/scripts/search.js Normal file
View File

@@ -0,0 +1,369 @@
(() => {
// Append the search dialog to the body
const siteSearch = document.createElement('div');
const scrollbarWidth = Math.abs(window.innerWidth - document.documentElement.clientWidth);
siteSearch.classList.add('search');
siteSearch.innerHTML = `
<div class="search__overlay"></div>
<dialog id="search-dialog" class="search__dialog">
<div class="search__content">
<div class="search__header">
<div id="search-combobox" class="search__input-wrapper">
<sl-icon name="search"></sl-icon>
<input
id="search-input"
class="search__input"
type="search"
placeholder="Search"
autocomplete="off"
autocorrect="off"
autocapitalize="off"
enterkeyhint="go"
spellcheck="false"
maxlength="100"
role="combobox"
aria-autocomplete="list"
aria-expanded="true"
aria-controls="search-listbox"
aria-haspopup="listbox"
aria-activedescendant
>
<button type="button" class="search__clear-button" aria-label="Clear entry" tabindex="-1" hidden>
<sl-icon name="x-circle-fill"></sl-icon>
</button>
</div>
</div>
<div class="search__body">
<ul
id="search-listbox"
class="search__results"
role="listbox"
aria-label="Search results"
></ul>
<div class="search__empty">No matching pages</div>
</div>
<footer class="search__footer">
<small><kbd>↑</kbd> <kbd>↓</kbd> Navigate</small>
<small><kbd>↲</kbd> Select</small>
<small><kbd>Esc</kbd> Close</small>
</footer>
</div>
</dialog>
`;
const overlay = siteSearch.querySelector('.search__overlay');
const dialog = siteSearch.querySelector('.search__dialog');
const input = siteSearch.querySelector('.search__input');
const clearButton = siteSearch.querySelector('.search__clear-button');
const results = siteSearch.querySelector('.search__results');
const version = document.documentElement.getAttribute('data-shoelace-version');
const animationDuration = 150;
const searchDebounce = 50;
let isShowing = false;
let searchTimeout;
let searchIndex;
let map;
const loadSearchIndex = new Promise(resolve => {
const key = `search_${version}`;
const cache = localStorage.getItem(key);
const wait = 'requestIdleCallback' in window ? requestIdleCallback : requestAnimationFrame;
// Cleanup older search indices (everything before this version)
try {
const items = { ...localStorage };
Object.keys(items).forEach(k => {
if (key > k) {
localStorage.removeItem(k);
}
});
} catch {
/* do nothing */
}
// Look for a cached index
try {
if (cache) {
const data = JSON.parse(cache);
searchIndex = window.lunr.Index.load(data.searchIndex);
map = data.map;
return resolve();
}
} catch {
/* do nothing */
}
// Wait until idle to fetch the index
wait(() => {
fetch('/assets/search.json')
.then(res => res.json())
.then(data => {
if (!window.lunr) {
console.error('The Lunr search client has not yet been loaded.');
}
searchIndex = window.lunr.Index.load(data.searchIndex);
map = data.map;
// Cache the search index for this version
if (version) {
try {
localStorage.setItem(key, JSON.stringify(data));
} catch (err) {
console.warn(`Unable to cache the search index: ${err}`);
}
}
resolve();
});
});
});
async function show() {
isShowing = true;
document.body.append(siteSearch);
document.body.classList.add('search-visible');
document.body.style.setProperty('--docs-search-scroll-lock-size', `${scrollbarWidth}px`);
clearButton.hidden = true;
requestAnimationFrame(() => input.focus());
updateResults();
dialog.showModal();
await Promise.all([
dialog.animate(
[
{ opacity: 0, transform: 'scale(.9)', transformOrigin: 'top' },
{ opacity: 1, transform: 'scale(1)', transformOrigin: 'top' }
],
{ duration: animationDuration }
).finished,
overlay.animate([{ opacity: 0 }, { opacity: 1 }], { duration: animationDuration }).finished
]);
dialog.addEventListener('mousedown', handleMouseDown);
dialog.addEventListener('keydown', handleKeyDown);
}
async function hide() {
isShowing = false;
await Promise.all([
dialog.animate(
[
{ opacity: 1, transform: 'scale(1)', transformOrigin: 'top' },
{ opacity: 0, transform: 'scale(.9)', transformOrigin: 'top' }
],
{ duration: animationDuration }
).finished,
overlay.animate([{ opacity: 1 }, { opacity: 0 }], { duration: animationDuration }).finished
]);
dialog.close();
input.blur(); // otherwise Safari will scroll to the bottom of the page on close
input.value = '';
document.body.classList.remove('search-visible');
document.body.style.removeProperty('--docs-search-scroll-lock-size');
siteSearch.remove();
updateResults();
dialog.removeEventListener('mousedown', handleMouseDown);
dialog.removeEventListener('keydown', handleKeyDown);
}
function handleInput() {
clearButton.hidden = input.value === '';
// Debounce search queries
clearTimeout(searchTimeout);
searchTimeout = setTimeout(() => updateResults(input.value), searchDebounce);
}
function handleClear() {
clearButton.hidden = true;
input.value = '';
input.focus();
updateResults();
}
function handleMouseDown(event) {
if (!event.target.closest('.search__content')) {
hide();
}
}
function handleKeyDown(event) {
// Close when pressing escape
if (event.key === 'Escape') {
event.preventDefault(); // prevent <dialog> from closing immediately so it can animate
event.stopImmediatePropagation();
hide();
return;
}
// Handle keyboard selections
if (['ArrowDown', 'ArrowUp', 'Home', 'End', 'Enter'].includes(event.key)) {
event.preventDefault();
const currentEl = results.querySelector('[data-selected="true"]');
const items = [...results.querySelectorAll('li')];
const index = items.indexOf(currentEl);
let nextEl;
if (items.length === 0) {
return;
}
switch (event.key) {
case 'ArrowUp':
nextEl = items[Math.max(0, index - 1)];
break;
case 'ArrowDown':
nextEl = items[Math.min(items.length - 1, index + 1)];
break;
case 'Home':
nextEl = items[0];
break;
case 'End':
nextEl = items[items.length - 1];
break;
case 'Enter':
currentEl?.querySelector('a')?.click();
break;
}
// Update the selected item
items.forEach(item => {
if (item === nextEl) {
input.setAttribute('aria-activedescendant', item.id);
item.setAttribute('data-selected', 'true');
nextEl.scrollIntoView({ block: 'nearest' });
} else {
item.setAttribute('data-selected', 'false');
}
});
}
}
async function updateResults(query = '') {
try {
await loadSearchIndex;
const hasQuery = query.length > 0;
const searchTerms = query
.split(' ')
.map((term, index, arr) => {
// Search API: https://lunrjs.com/guides/searching.html
if (index === arr.length - 1) {
// The last term is not mandatory and 1x fuzzy. We also duplicate it with a wildcard to match partial words
// as the user types.
return `${term}~1 ${term}*`;
} else {
// All other terms are mandatory and 1x fuzzy
return `+${term}~1`;
}
})
.join(' ');
const matches = hasQuery ? searchIndex.search(searchTerms) : [];
const hasResults = hasQuery && matches.length > 0;
siteSearch.classList.toggle('search--has-results', hasQuery && hasResults);
siteSearch.classList.toggle('search--no-results', hasQuery && !hasResults);
input.setAttribute('aria-activedescendant', '');
results.innerHTML = '';
matches.forEach((match, index) => {
const page = map[match.ref];
const li = document.createElement('li');
const a = document.createElement('a');
const displayTitle = page.title ?? '';
const displayDescription = page.description ?? '';
const displayUrl = page.url.replace(/^\//, '');
let icon = 'file-text';
a.setAttribute('role', 'option');
a.setAttribute('id', `search-result-item-${match.ref}`);
if (page.url.includes('getting-started/')) {
icon = 'lightbulb';
}
if (page.url.includes('resources/')) {
icon = 'book';
}
if (page.url.includes('components/')) {
icon = 'puzzle';
}
if (page.url.includes('tokens/')) {
icon = 'palette2';
}
if (page.url.includes('utilities/')) {
icon = 'wrench';
}
if (page.url.includes('tutorials/')) {
icon = 'joystick';
}
li.classList.add('search__result');
li.setAttribute('role', 'option');
li.setAttribute('id', `search-result-item-${match.ref}`);
li.setAttribute('data-selected', index === 0 ? 'true' : 'false');
a.href = page.url;
a.innerHTML = `
<div class="search__result-icon" aria-hidden="true">
<sl-icon name="${icon}"></sl-icon>
</div>
<div class="search__result__details">
<div class="search__result-title"></div>
<div class="search__result-description"></div>
<div class="search__result-url"></div>
</div>
`;
a.querySelector('.search__result-title').textContent = displayTitle;
a.querySelector('.search__result-description').textContent = displayDescription;
a.querySelector('.search__result-url').textContent = displayUrl;
li.appendChild(a);
results.appendChild(li);
});
} catch {
// Ignore query errors as the user types
}
}
// Show the search dialog when clicking on data-plugin="search"
document.addEventListener('click', event => {
const searchButton = event.target.closest('[data-plugin="search"]');
if (searchButton) {
show();
}
});
// Show the search dialog when slash (or CMD+K) is pressed and focus is not inside a form element
document.addEventListener('keydown', event => {
if (
!isShowing &&
(event.key === '/' || (event.key === 'k' && (event.metaKey || event.ctrlKey))) &&
!event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
) {
event.preventDefault();
show();
}
});
input.addEventListener('input', handleInput);
clearButton.addEventListener('click', handleClear);
// Close when a result is selected
results.addEventListener('click', event => {
if (event.target.closest('a')) {
hide();
}
});
})();

173
docs/assets/styles/code-previews.css Normal file
View File

@@ -0,0 +1,173 @@
/* Interactive code blocks */
.code-preview {
position: relative;
border-radius: 3px;
background-color: var(--sl-color-neutral-50);
margin-bottom: 1.5rem;
}
.code-preview__preview {
position: relative;
border: solid 1px var(--sl-color-neutral-200);
border-bottom: none;
border-top-left-radius: 3px;
border-top-right-radius: 3px;
background-color: var(--sl-color-neutral-0);
min-width: 20rem;
max-width: 100%;
padding: 1.5rem 3.25rem 1.5rem 1.5rem;
}
/* Block the preview while dragging to prevent iframes from intercepting drag events */
.code-preview__preview--dragging:after {
content: '';
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
opacity: 0;
cursor: ew-resize;
}
.code-preview__resizer {
display: flex;
align-items: center;
justify-content: center;
position: absolute;
top: 0;
right: 0;
bottom: 0;
width: 1.75rem;
font-size: 20px;
color: var(--sl-color-neutral-600);
background-color: var(--sl-color-neutral-0);
border-left: solid 1px var(--sl-color-neutral-200);
border-top-right-radius: 3px;
cursor: ew-resize;
}
@media screen and (max-width: 600px) {
.code-preview__preview {
padding-right: 1.5rem;
}
.code-preview__resizer {
display: none;
}
}
.code-preview__source {
border: solid 1px var(--sl-color-neutral-200);
border-bottom: none;
border-radius: 0 !important;
display: none;
}
.code-preview--expanded .code-preview__source {
display: block;
}
.code-preview__source pre {
margin: 0;
}
.code-preview__buttons {
position: relative;
border: solid 1px var(--sl-color-neutral-200);
border-bottom-left-radius: 3px;
border-bottom-right-radius: 3px;
display: flex;
}
.code-preview__button {
flex: 0 0 auto;
height: 2.5rem;
min-width: 2.5rem;
border: none;
border-radius: 0;
background: var(--sl-color-neutral-0);
font: inherit;
font-size: 0.7rem;
font-weight: 500;
text-transform: uppercase;
color: var(--sl-color-neutral-600);
padding: 0 1rem;
cursor: pointer;
}
.code-preview__button:not(:last-of-type) {
border-right: solid 1px var(--sl-color-neutral-200);
}
.code-preview__button--html,
.code-preview__button--react {
width: 70px;
display: flex;
place-items: center;
justify-content: center;
}
.code-preview__button--selected {
font-weight: 700;
color: var(--sl-color-primary-600);
}
.code-preview__button--codepen {
display: flex;
place-items: center;
width: 6rem;
}
.code-preview__button:first-of-type {
border-bottom-left-radius: 3px;
}
.code-preview__button:last-of-type {
border-bottom-right-radius: 3px;
}
.code-preview__button:hover,
.code-preview__button:active {
box-shadow: 0 0 0 1px var(--sl-color-primary-400);
border-right-color: transparent;
background-color: var(--sl-color-primary-50);
color: var(--sl-color-primary-600);
z-index: 1;
}
.code-preview__button:focus-visible {
outline: none;
outline: var(--sl-focus-ring);
z-index: 2;
}
.code-preview__toggle {
position: relative;
display: flex;
flex: 1 1 auto;
align-items: center;
justify-content: center;
width: 100%;
color: var(--sl-color-neutral-600);
cursor: pointer;
}
.code-preview__toggle svg {
width: 1em;
height: 1em;
margin-left: 0.25rem;
}
.code-preview--expanded .code-preview__toggle svg {
transform: rotate(180deg);
}
/* We can apply data-flavor="html|react" to any element on the page to toggle it when the flavor changes */
.flavor-html [data-flavor]:not([data-flavor='html']) {
display: none;
}
.flavor-react [data-flavor]:not([data-flavor='react']) {
display: none;
}

1526
docs/assets/styles/docs.css
View File

File diff suppressed because it is too large Load Diff

347
docs/assets/styles/search.css Normal file
View File

@@ -0,0 +1,347 @@
/* Search plugin */
:root,
:root.sl-theme-dark {
--docs-search-box-background: var(--sl-color-neutral-0);
--docs-search-box-border-width: 1px;
--docs-search-box-border-color: var(--sl-color-neutral-300);
--docs-search-box-color: var(--sl-color-neutral-600);
--docs-search-dialog-background: var(--sl-color-neutral-0);
--docs-search-border-width: var(--docs-border-width);
--docs-search-border-color: var(--docs-border-color);
--docs-search-text-color: var(--sl-color-neutral-900);
--docs-search-text-color-muted: var(--sl-color-neutral-500);
--docs-search-font-weight-normal: var(--sl-font-weight-normal);
--docs-search-font-weight-semibold: var(--sl-font-weight-semibold);
--docs-search-border-radius: calc(2 * var(--docs-border-radius));
--docs-search-accent-color: var(--sl-color-primary-600);
--docs-search-icon-color: var(--sl-color-neutral-500);
--docs-search-icon-color-active: var(--sl-color-neutral-600);
--docs-search-shadow: var(--docs-shadow-x-large);
--docs-search-result-background-hover: var(--sl-color-neutral-100);
--docs-search-result-color-hover: var(--sl-color-neutral-900);
--docs-search-result-background-active: var(--sl-color-primary-600);
--docs-search-result-color-active: var(--sl-color-neutral-0);
--docs-search-focus-ring: var(--sl-focus-ring);
--docs-search-overlay-background: rgb(0 0 0 / 0.33);
}
:root.sl-theme-dark {
--docs-search-overlay-background: rgb(71 71 71 / 0.33);
}
body.search-visible {
padding-right: var(--docs-search-scroll-lock-size) !important;
overflow: hidden !important;
}
/* Search box */
.search-box {
flex: 1 1 auto;
display: flex;
align-items: center;
width: 100%;
border: none;
border-radius: 9999px;
background: var(--docs-search-box-background);
border: solid var(--docs-search-box-border-width) var(--docs-search-box-border-color);
font: inherit;
color: var(--docs-search-box-color);
padding: 0.75rem 1rem;
margin: var(--sl-spacing-large) 0;
cursor: pointer;
}
.search-box span {
flex: 1 1 auto;
width: 1rem;
height: 1rem;
text-align: left;
line-height: 1;
margin: 0 0.75rem;
}
.search-box:focus {
outline: none;
}
.search-box:focus-visible {
outline: var(--docs-search-focus-ring);
}
/* Site search */
.search {
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
z-index: 9999;
}
.search[hidden] {
display: none;
}
.search__overlay {
position: absolute;
top: 0;
left: 0;
right: 0;
bottom: 0;
background: var(--docs-search-overlay-background);
z-index: -1;
}
.search__dialog {
width: 100%;
height: 100%;
max-width: none;
max-height: none;
background: transparent;
border: none;
padding: 0;
margin: 0;
}
.search__dialog:focus {
outline: none;
}
.search__dialog::backdrop {
display: none;
}
/* Fixes an iOS Safari 16.4 bug that draws the parent element's border radius incorrectly when showing/hiding results */
.search__header {
background-color: var(--docs-search-dialog-background);
border-radius: var(--docs-search-border-radius);
}
.search--has-results .search__header {
border-top-left-radius: var(--docs-search-border-radius);
border-top-right-radius: var(--docs-search-border-radius);
border-bottom-left-radius: 0;
border-bottom-right-radius: 0;
}
.search__content {
display: flex;
flex-direction: column;
width: 100%;
max-width: 500px;
max-height: calc(100vh - 20rem);
background-color: var(--docs-search-dialog-background);
border-radius: var(--docs-search-border-radius);
box-shadow: var(--docs-search-shadow);
padding: 0;
margin: 10rem auto;
}
@media screen and (max-width: 900px) {
.search__content {
max-width: calc(100% - 2rem);
max-height: calc(90svh);
margin: 4vh 1rem;
}
}
.search__input-wrapper {
display: flex;
align-items: center;
}
.search__input-wrapper sl-icon {
width: 1.5rem;
height: 1.5rem;
flex: 0 0 auto;
color: var(--docs-search-icon-color);
margin: 0 1.5rem;
}
.search__clear-button {
display: flex;
background: none;
border: none;
font: inherit;
padding: 0;
margin: 0;
cursor: pointer;
}
.search__clear-button[hidden] {
display: none;
}
.search__clear-button:active sl-icon {
color: var(--docs-search-icon-color-active);
}
.search__input {
flex: 1 1 auto;
min-width: 0;
border: none;
font: inherit;
font-size: 1.5rem;
font-weight: var(--docs-search-font-weight-normal);
color: var(--docs-search-text-color);
background: transparent;
padding: 1rem 0;
margin: 0;
}
.search__input::placeholder {
color: var(--docs-search-text-color-muted);
}
.search__input::-webkit-search-decoration,
.search__input::-webkit-search-cancel-button,
.search__input::-webkit-search-results-button,
.search__input::-webkit-search-results-decoration {
display: none;
}
.search__input:focus,
.search__input:focus-visible {
outline: none;
}
.search__body {
flex: 1 1 auto;
overflow: auto;
}
.search--has-results .search__body {
border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
}
.search__results {
display: none;
line-height: 1.2;
list-style: none;
padding: 0.5rem 0;
margin: 0;
}
.search--has-results .search__results {
display: block;
}
.search__results a {
display: block;
text-decoration: none;
padding: 0.5rem 1.5rem;
}
.search__results a:focus-visible {
outline: var(--docs-search-focus-ring);
}
.search__results li a:hover,
.search__results li a:hover small {
background-color: var(--docs-search-result-background-hover);
color: var(--docs-search-result-color-hover);
}
.search__results li[data-selected='true'] a,
.search__results li[data-selected='true'] a * {
outline: none;
background-color: var(--docs-search-result-background-active);
color: var(--docs-search-result-color-active);
}
.search__results h3 {
font-weight: var(--docs-search-font-weight-semibold);
margin: 0;
}
.search__results small {
display: block;
color: var(--docs-search-text-color-muted);
}
.search__result {
padding: 0;
margin: 0;
}
.search__result a {
display: flex;
align-items: center;
gap: 1rem;
}
.search__result-icon {
flex: 0 0 auto;
display: flex;
color: var(--docs-search-text-color-muted);
}
.search__result-icon sl-icon {
font-size: 1.5rem;
}
.search__result__details {
width: calc(100% - 3rem);
}
.search__result-title,
.search__result-description,
.search__result-url {
max-width: 400px;
line-height: 1.3;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.search__result-title {
font-size: 1.2rem;
font-weight: var(--docs-search-font-weight-semibold);
color: var(--docs-search-accent-color);
}
.search__result-description {
font-size: 0.875rem;
color: var(--docs-search-text-color);
}
.search__result-url {
font-size: 0.875rem;
color: var(--docs-search-text-color-muted);
}
.search__empty {
display: none;
border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
text-align: center;
color: var(--docs-search-text-color-muted);
padding: 2rem;
}
.search--no-results .search__empty {
display: block;
}
.search__footer {
display: flex;
justify-content: center;
gap: 2rem;
border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
border-bottom-left-radius: inherit;
border-bottom-right-radius: inherit;
padding: 1rem;
}
.search__footer small {
color: var(--docs-search-text-color-muted);
}
.search__footer small kbd:last-of-type {
margin-right: 0.25rem;
}
@media screen and (max-width: 900px) {
.search__footer {
display: none;
}
}

217
docs/eleventy.config.cjs Normal file
View File

@@ -0,0 +1,217 @@
/* eslint-disable no-invalid-this */
const fs = require('fs');
const path = require('path');
const lunr = require('lunr');
const { capitalCase } = require('change-case');
const { JSDOM } = require('jsdom');
const { customElementsManifest, getAllComponents } = require('./_utilities/cem.cjs');
const shoelaceFlavoredMarkdown = require('./_utilities/markdown.cjs');
const activeLinks = require('./_utilities/active-links.cjs');
const anchorHeadings = require('./_utilities/anchor-headings.cjs');
const codePreviews = require('./_utilities/code-previews.cjs');
const copyCodeButtons = require('./_utilities/copy-code-buttons.cjs');
const externalLinks = require('./_utilities/external-links.cjs');
const highlightCodeBlocks = require('./_utilities/highlight-code.cjs');
const tableOfContents = require('./_utilities/table-of-contents.cjs');
const prettier = require('./_utilities/prettier.cjs');
const scrollingTables = require('./_utilities/scrolling-tables.cjs');
const typography = require('./_utilities/typography.cjs');
const assetsDir = 'assets';
const allComponents = getAllComponents();
let hasBuiltSearchIndex = false;
module.exports = function (eleventyConfig) {
//
// Global data
//
eleventyConfig.addGlobalData('baseUrl', 'https://shoelace.style/'); // the production URL
eleventyConfig.addGlobalData('layout', 'default'); // make 'default' the default layout
eleventyConfig.addGlobalData('toc', true); // enable the table of contents
eleventyConfig.addGlobalData('meta', {
title: 'Shoelace',
description: 'A forward-thinking library of web components.',
image: 'images/og-image.png',
version: customElementsManifest.package.version,
components: allComponents
});
//
// Layout aliases
//
eleventyConfig.addLayoutAlias('default', 'default.njk');
//
// Copy assets
//
eleventyConfig.addPassthroughCopy(assetsDir);
eleventyConfig.setServerPassthroughCopyBehavior('passthrough'); // emulates passthrough copy during --serve
//
// Functions
//
// Generates a URL relative to the site's root
eleventyConfig.addNunjucksGlobal('rootUrl', (value = '', absolute = false) => {
value = path.join('/', value);
return absolute ? new URL(value, eleventyConfig.globalData.baseUrl).toString() : value;
});
// Generates a URL relative to the site's asset directory
eleventyConfig.addNunjucksGlobal('assetUrl', (value = '', absolute = false) => {
value = path.join(`/${assetsDir}`, value);
return absolute ? new URL(value, eleventyConfig.globalData.baseUrl).toString() : value;
});
// Fetches a specific component's metadata
eleventyConfig.addNunjucksGlobal('getComponent', tagName => {
const component = allComponents.find(c => c.tagName === tagName);
if (!component) {
throw new Error(
`Unable to find a component called "${tagName}". Make sure the file name is the same as the component's tag ` +
`name (minus the sl- prefix).`
);
}
return component;
});
//
// Custom markdown syntaxes
//
eleventyConfig.setLibrary('md', shoelaceFlavoredMarkdown);
//
// Filters
//
eleventyConfig.addFilter('markdown', content => {
return shoelaceFlavoredMarkdown.render(content);
});
eleventyConfig.addFilter('markdownInline', content => {
return shoelaceFlavoredMarkdown.renderInline(content);
});
eleventyConfig.addFilter('classNameToComponentName', className => {
let name = capitalCase(className.replace(/^Sl/, ''));
if (name === 'Qr Code') name = 'QR Code'; // manual override
return name;
});
eleventyConfig.addFilter('removeSlPrefix', tagName => {
return tagName.replace(/^sl-/, '');
});
//
// Transforms
//
eleventyConfig.addTransform('html-transform', function (content) {
// Parse the template and get a Document object
const doc = new JSDOM(content, {
// We must set a default URL so links are parsed with a hostname. Let's use a bogus TLD so we can easily
// identify which ones are internal and which ones are external.
url: `https://internal/`
}).window.document;
// DOM transforms
activeLinks(doc, { pathname: this.page.url });
anchorHeadings(doc, {
within: '#content .content__body',
levels: ['h2', 'h3', 'h4', 'h5']
});
tableOfContents(doc, {
levels: ['h2', 'h3'],
container: '#content .content__toc > ul',
within: '#content .content__body'
});
codePreviews(doc);
externalLinks(doc, { target: '_blank' });
highlightCodeBlocks(doc);
scrollingTables(doc);
copyCodeButtons(doc); // must be after codePreviews + highlightCodeBlocks
typography(doc, '#content');
// Serialize the Document object to an HTML string and prepend the doctype
content = `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
// String transforms
content = prettier(content);
return content;
});
//
// Build a search index
//
eleventyConfig.on('eleventy.after', async ({ results }) => {
// We only want to build the search index on the first run so all pages get indexed.
if (hasBuiltSearchIndex) {
return;
}
const map = {};
const searchIndexFilename = path.join(eleventyConfig.dir.output, assetsDir, 'search.json');
const lunrFilename = path.join(eleventyConfig.dir.output, assetsDir, 'scripts/lunr.js');
const searchIndex = lunr(function () {
// The search index uses these field names extensively, so shortening them can save some serious bytes. The
// initial index file went from 468 KB => 401 KB by using single-character names!
this.ref('id'); // id
this.field('t', { boost: 50 }); // title
this.field('h', { boost: 25 }); // headings
this.field('c'); // content
results.forEach((result, index) => {
const url = path.join('/', path.relative(eleventyConfig.dir.output, result.outputPath));
const doc = new JSDOM(result.content, {
// We must set a default URL so links are parsed with a hostname. Let's use a bogus TLD so we can easily
// identify which ones are internal and which ones are external.
url: `https://internal/`
}).window.document;
const content = doc.querySelector('#content');
// Get title and headings
const title = (doc.querySelector('title')?.textContent || path.basename(result.outputPath)).trim();
const headings = [...content.querySelectorAll('h1, h2, h3, h4')]
.map(heading => heading.textContent)
.join(' ')
.replace(/\s+/g, ' ')
.trim();
// Remove code blocks and whitespace from content
[...content.querySelectorAll('code[class|=language]')].forEach(code => code.remove());
const textContent = content.textContent.replace(/\s+/g, ' ').trim();
// Update the index and map
this.add({ id: index, t: title, h: headings, c: textContent });
map[index] = { title, url };
});
});
// Copy the Lunr search client and write the index
fs.copyFileSync('../node_modules/lunr/lunr.min.js', lunrFilename);
fs.writeFileSync(searchIndexFilename, JSON.stringify({ searchIndex, map }), 'utf-8');
hasBuiltSearchIndex = true;
});
//
// Dev server options (see https://www.11ty.dev/docs/dev-server/#options)
//
eleventyConfig.setServerOptions({
domDiff: false, // disable dom diffing so custom elements don't break on reload,
port: 4000, // if port 4000 is taken, 11ty will use the next one available
watch: [] // additional files to watch that will trigger server updates (array of paths or globs)
});
//
// 11ty config
//
return {
dir: {
input: 'pages',
output: '../_site',
includes: '../_includes' // resolved relative to the input dir
},
markdownTemplateEngine: 'njk', // use Nunjucks instead of Liquid for markdown files
templateEngineOverride: ['njk'] // just Nunjucks and then markdown
};
};

19
docs/pages/404.md Normal file
View File

@@ -0,0 +1,19 @@
---
meta:
title: Page Not Found
description: "The page you were looking for couldn't be found."
permalink: 404.html
toc: false
---
<div style="text-align: center;">
# Page Not Found
![A UFO takes one of the little worker monsters](/assets/images/undraw-taken.svg)
The page you were looking for couldn't be found.
Press [[/]] to search, or [head back to the homepage](/).
</div>

436
docs/pages/components/alert.md Normal file
View File

@@ -0,0 +1,436 @@
---
meta:
title: Alert
description: Alerts are used to display important messages inline or as toast notifications.
layout: component
---
```html:preview
<sl-alert open>
<sl-icon slot="icon" name="info-circle"></sl-icon>
This is a standard alert. You can customize its content and even the icon.
</sl-alert>
```
```jsx:react
import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlAlert open>
<SlIcon slot="icon" name="info-circle" />
This is a standard alert. You can customize its content and even the icon.
</SlAlert>
);
```
:::tip
Alerts will not be visible if the `open` attribute is not present.
:::
## Examples
### Variants
Set the `variant` attribute to change the alert's variant.
```html:preview
<sl-alert variant="primary" open>
<sl-icon slot="icon" name="info-circle"></sl-icon>
<strong>This is super informative</strong><br />
You can tell by how pretty the alert is.
</sl-alert>
<br />
<sl-alert variant="success" open>
<sl-icon slot="icon" name="check2-circle"></sl-icon>
<strong>Your changes have been saved</strong><br />
You can safely exit the app now.
</sl-alert>
<br />
<sl-alert variant="neutral" open>
<sl-icon slot="icon" name="gear"></sl-icon>
<strong>Your settings have been updated</strong><br />
Settings will take affect on next login.
</sl-alert>
<br />
<sl-alert variant="warning" open>
<sl-icon slot="icon" name="exclamation-triangle"></sl-icon>
<strong>Your session has ended</strong><br />
Please login again to continue.
</sl-alert>
<br />
<sl-alert variant="danger" open>
<sl-icon slot="icon" name="exclamation-octagon"></sl-icon>
<strong>Your account has been deleted</strong><br />
We're very sorry to see you go!
</sl-alert>
```
```jsx:react
import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlAlert variant="primary" open>
<SlIcon slot="icon" name="info-circle" />
<strong>This is super informative</strong>
<br />
You can tell by how pretty the alert is.
</SlAlert>
<br />
<SlAlert variant="success" open>
<SlIcon slot="icon" name="check2-circle" />
<strong>Your changes have been saved</strong>
<br />
You can safely exit the app now.
</SlAlert>
<br />
<SlAlert variant="neutral" open>
<SlIcon slot="icon" name="gear" />
<strong>Your settings have been updated</strong>
<br />
Settings will take affect on next login.
</SlAlert>
<br />
<SlAlert variant="warning" open>
<SlIcon slot="icon" name="exclamation-triangle" />
<strong>Your session has ended</strong>
<br />
Please login again to continue.
</SlAlert>
<br />
<SlAlert variant="danger" open>
<SlIcon slot="icon" name="exclamation-octagon" />
<strong>Your account has been deleted</strong>
<br />
We're very sorry to see you go!
</SlAlert>
</>
);
```
### Closable
Add the `closable` attribute to show a close button that will hide the alert.
```html:preview
<sl-alert variant="primary" open closable class="alert-closable">
<sl-icon slot="icon" name="info-circle"></sl-icon>
You can close this alert any time!
</sl-alert>
<script>
const alert = document.querySelector('.alert-closable');
alert.addEventListener('sl-after-hide', () => {
setTimeout(() => (alert.open = true), 2000);
});
</script>
```
```jsx:react
import { useState } from 'react';
import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(true);
function handleHide() {
setOpen(false);
setTimeout(() => setOpen(true), 2000);
}
return (
<SlAlert open={open} closable onSlAfterHide={handleHide}>
<SlIcon slot="icon" name="info-circle" />
You can close this alert any time!
</SlAlert>
);
};
```
### Without Icons
Icons are optional. Simply omit the `icon` slot if you don't want them.
```html:preview
<sl-alert variant="primary" open> Nothing fancy here, just a simple alert. </sl-alert>
```
```jsx:react
import { SlAlert } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlAlert variant="primary" open>
Nothing fancy here, just a simple alert.
</SlAlert>
);
```
### Duration
Set the `duration` attribute to automatically hide an alert after a period of time. This is useful for alerts that don't require acknowledgement.
```html:preview
<div class="alert-duration">
<sl-button variant="primary">Show Alert</sl-button>
<sl-alert variant="primary" duration="3000" closable>
<sl-icon slot="icon" name="info-circle"></sl-icon>
This alert will automatically hide itself after three seconds, unless you interact with it.
</sl-alert>
</div>
<script>
const container = document.querySelector('.alert-duration');
const button = container.querySelector('sl-button');
const alert = container.querySelector('sl-alert');
button.addEventListener('click', () => alert.show());
</script>
<style>
.alert-duration sl-alert {
margin-top: var(--sl-spacing-medium);
}
</style>
```
```jsx:react
import { useState } from 'react';
import { SlAlert, SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
const css = `
.alert-duration sl-alert {
margin-top: var(--sl-spacing-medium);
}
`;
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<div className="alert-duration">
<SlButton variant="primary" onClick={() => setOpen(true)}>
Show Alert
</SlButton>
<SlAlert variant="primary" duration="3000" open={open} closable onSlAfterHide={() => setOpen(false)}>
<SlIcon slot="icon" name="info-circle" />
This alert will automatically hide itself after three seconds, unless you interact with it.
</SlAlert>
</div>
<style>{css}</style>
</>
);
};
```
### Toast Notifications
To display an alert as a toast notification, or "toast", create the alert and call its `toast()` method. This will move the alert out of its position in the DOM and into [the toast stack](#the-toast-stack) where it will be shown. Once dismissed, it will be removed from the DOM completely. To reuse a toast, store a reference to it and call `toast()` again later on.
You should always use the `closable` attribute so users can dismiss the notification. It's also common to set a reasonable `duration` when the notification doesn't require acknowledgement.
```html:preview
<div class="alert-toast">
<sl-button variant="primary">Primary</sl-button>
<sl-button variant="success">Success</sl-button>
<sl-button variant="neutral">Neutral</sl-button>
<sl-button variant="warning">Warning</sl-button>
<sl-button variant="danger">Danger</sl-button>
<sl-alert variant="primary" duration="3000" closable>
<sl-icon slot="icon" name="info-circle"></sl-icon>
<strong>This is super informative</strong><br />
You can tell by how pretty the alert is.
</sl-alert>
<sl-alert variant="success" duration="3000" closable>
<sl-icon slot="icon" name="check2-circle"></sl-icon>
<strong>Your changes have been saved</strong><br />
You can safely exit the app now.
</sl-alert>
<sl-alert variant="neutral" duration="3000" closable>
<sl-icon slot="icon" name="gear"></sl-icon>
<strong>Your settings have been updated</strong><br />
Settings will take affect on next login.
</sl-alert>
<sl-alert variant="warning" duration="3000" closable>
<sl-icon slot="icon" name="exclamation-triangle"></sl-icon>
<strong>Your session has ended</strong><br />
Please login again to continue.
</sl-alert>
<sl-alert variant="danger" duration="3000" closable>
<sl-icon slot="icon" name="exclamation-octagon"></sl-icon>
<strong>Your account has been deleted</strong><br />
We're very sorry to see you go!
</sl-alert>
</div>
<script>
const container = document.querySelector('.alert-toast');
['primary', 'success', 'neutral', 'warning', 'danger'].map(variant => {
const button = container.querySelector(`sl-button[variant="${variant}"]`);
const alert = container.querySelector(`sl-alert[variant="${variant}"]`);
button.addEventListener('click', () => alert.toast());
});
</script>
```
```jsx:react
import { useRef } from 'react';
import { SlAlert, SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
function showToast(alert) {
alert.toast();
}
const App = () => {
const primary = useRef(null);
const success = useRef(null);
const neutral = useRef(null);
const warning = useRef(null);
const danger = useRef(null);
return (
<>
<SlButton variant="primary" onClick={() => primary.current.toast()}>
Primary
</SlButton>
<SlButton variant="success" onClick={() => success.current.toast()}>
Success
</SlButton>
<SlButton variant="neutral" onClick={() => neutral.current.toast()}>
Neutral
</SlButton>
<SlButton variant="warning" onClick={() => warning.current.toast()}>
Warning
</SlButton>
<SlButton variant="danger" onClick={() => danger.current.toast()}>
Danger
</SlButton>
<SlAlert ref={primary} variant="primary" duration="3000" closable>
<SlIcon slot="icon" name="info-circle" />
<strong>This is super informative</strong>
<br />
You can tell by how pretty the alert is.
</SlAlert>
<SlAlert ref={success} variant="success" duration="3000" closable>
<SlIcon slot="icon" name="check2-circle" />
<strong>Your changes have been saved</strong>
<br />
You can safely exit the app now.
</SlAlert>
<SlAlert ref={neutral} variant="neutral" duration="3000" closable>
<SlIcon slot="icon" name="gear" />
<strong>Your settings have been updated</strong>
<br />
Settings will take affect on next login.
</SlAlert>
<SlAlert ref={warning} variant="warning" duration="3000" closable>
<SlIcon slot="icon" name="exclamation-triangle" />
<strong>Your session has ended</strong>
<br />
Please login again to continue.
</SlAlert>
<SlAlert ref={danger} variant="danger" duration="3000" closable>
<SlIcon slot="icon" name="exclamation-octagon" />
<strong>Your account has been deleted</strong>
<br />
We're very sorry to see you go!
</SlAlert>
</>
);
};
```
### Creating Toasts Imperatively
For convenience, you can create a utility that emits toast notifications with a function call rather than composing them in your HTML. To do this, generate the alert with JavaScript, append it to the body, and call the `toast()` method as shown in the example below.
```html:preview
<div class="alert-toast-wrapper">
<sl-button variant="primary">Create Toast</sl-button>
</div>
<script>
const container = document.querySelector('.alert-toast-wrapper');
const button = container.querySelector('sl-button');
let count = 0;
// Always escape HTML for text arguments!
function escapeHtml(html) {
const div = document.createElement('div');
div.textContent = html;
return div.innerHTML;
}
// Custom function to emit toast notifications
function notify(message, variant = 'primary', icon = 'info-circle', duration = 3000) {
const alert = Object.assign(document.createElement('sl-alert'), {
variant,
closable: true,
duration: duration,
innerHTML: `
<sl-icon name="${icon}" slot="icon"></sl-icon>
${escapeHtml(message)}
`
});
document.body.append(alert);
return alert.toast();
}
button.addEventListener('click', () => {
notify(`This is custom toast #${++count}`);
});
</script>
```
### The Toast Stack
The toast stack is a fixed position singleton element created and managed internally by the alert component. It will be added and removed from the DOM as needed when toasts are shown. When more than one toast is visible, they will stack vertically in the toast stack.
By default, the toast stack is positioned at the top-right of the viewport. You can change its position by targeting `.sl-toast-stack` in your stylesheet. To make toasts appear at the top-left of the viewport, for example, use the following styles.
```css
.sl-toast-stack {
left: 0;
right: auto;
}
```
:::tip
By design, it is not possible to show toasts in more than one stack simultaneously. Such behavior is confusing and makes for a poor user experience.
:::

130
docs/pages/components/animated-image.md Normal file
View File

@@ -0,0 +1,130 @@
---
meta:
title: Animated Image
description: A component for displaying animated GIFs and WEBPs that play and pause on interaction.
layout: component
---
```html:preview
<sl-animated-image
src="https://shoelace.style/assets/images/walk.gif"
alt="Animation of untied shoes walking on pavement"
></sl-animated-image>
```
```jsx:react
import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlAnimatedImage
src="https://shoelace.style/assets/images/walk.gif"
alt="Animation of untied shoes walking on pavement"
/>
);
```
:::tip
This component uses `<canvas>` to draw freeze frames, so images are subject to [cross-origin restrictions](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image).
:::
## Examples
### WEBP Images
Both GIF and WEBP images are supported.
```html:preview
<sl-animated-image
src="https://shoelace.style/assets/images/tie.webp"
alt="Animation of a shoe being tied"
></sl-animated-image>
```
```jsx:react
import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlAnimatedImage src="https://shoelace.style/assets/images/tie.webp" alt="Animation of a shoe being tied" />
);
```
### Setting a Width and Height
To set a custom size, apply a width and/or height to the host element.
```html:preview
<sl-animated-image
src="https://shoelace.style/assets/images/walk.gif"
alt="Animation of untied shoes walking on pavement"
style="width: 150px; height: 200px;"
>
</sl-animated-image>
```
{% raw %}
```jsx:react
import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlAnimatedImage
src="https://shoelace.style/assets/images/walk.gif"
alt="Animation of untied shoes walking on pavement"
style={{ width: '150px', height: '200px' }}
/>
);
```
{% endraw %}
### Customizing the Control Box
You can change the appearance and location of the control box by targeting the `control-box` part in your styles.
```html:preview
<sl-animated-image
src="https://shoelace.style/assets/images/walk.gif"
alt="Animation of untied shoes walking on pavement"
class="animated-image-custom-control-box"
></sl-animated-image>
<style>
.animated-image-custom-control-box::part(control-box) {
top: auto;
right: auto;
bottom: 1rem;
left: 1rem;
background-color: deeppink;
border: none;
color: pink;
}
</style>
```
```jsx:react
import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
const css = `
.animated-image-custom-control-box::part(control-box) {
top: auto;
right: auto;
bottom: 1rem;
left: 1rem;
background-color: deeppink;
border: none;
color: pink;
}
`;
const App = () => (
<>
<SlAnimatedImage
className="animated-image-custom-control-box"
src="https://shoelace.style/assets/images/walk.gif"
alt="Animation of untied shoes walking on pavement"
/>
<style>{css}</style>
</>
);
```

347
docs/pages/components/animation.md Normal file
View File

@@ -0,0 +1,347 @@
---
meta:
title: Animation
description: Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes.
layout: component
---
To animate an element, wrap it in `<sl-animation>` and set an animation `name`. The animation will not start until you add the `play` attribute. Refer to the [properties table](#properties) for a list of all animation options.
```html:preview
<div class="animation-overview">
<sl-animation name="bounce" duration="2000" play><div class="box"></div></sl-animation>
<sl-animation name="jello" duration="2000" play><div class="box"></div></sl-animation>
<sl-animation name="heartBeat" duration="2000" play><div class="box"></div></sl-animation>
<sl-animation name="flip" duration="2000" play><div class="box"></div></sl-animation>
</div>
<style>
.animation-overview .box {
display: inline-block;
width: 100px;
height: 100px;
background-color: var(--sl-color-primary-600);
margin: 1.5rem;
}
</style>
```
```jsx:react
import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
const css = `
.animation-overview .box {
display: inline-block;
width: 100px;
height: 100px;
background-color: var(--sl-color-primary-600);
margin: 1.5rem;
}
`;
const App = () => (
<>
<div class="animation-overview">
<SlAnimation name="bounce" duration={2000} play>
<div class="box" />
</SlAnimation>
<SlAnimation name="jello" duration={2000} play>
<div class="box" />
</SlAnimation>
<SlAnimation name="heartBeat" duration={2000} play>
<div class="box" />
</SlAnimation>
<SlAnimation name="flip" duration={2000} play>
<div class="box" />
</SlAnimation>
</div>
<style>{css}</style>
</>
);
```
:::tip
The animation will only be applied to the first child element found in `<sl-animation>`.
:::
## Examples
### Animations & Easings
This example demonstrates all of the baked-in animations and easings. Animations are based on those found in the popular [Animate.css](https://animate.style/) library.
```html:preview
<div class="animation-sandbox">
<sl-animation name="bounce" easing="ease-in-out" duration="2000" play>
<div class="box"></div>
</sl-animation>
<div class="controls">
<sl-select label="Animation" value="bounce"></sl-select>
<sl-select label="Easing" value="linear"></sl-select>
<sl-input label="Playback Rate" type="number" min="0" max="2" step=".25" value="1"></sl-input>
</div>
</div>
<script type="module">
import { getAnimationNames, getEasingNames } from '/dist/utilities/animation.js';
const container = document.querySelector('.animation-sandbox');
const animation = container.querySelector('sl-animation');
const animationName = container.querySelector('.controls sl-select:nth-child(1)');
const easingName = container.querySelector('.controls sl-select:nth-child(2)');
const playbackRate = container.querySelector('sl-input[type="number"]');
const animations = getAnimationNames();
const easings = getEasingNames();
animations.map(name => {
const option = Object.assign(document.createElement('sl-option'), {
textContent: name,
value: name
});
animationName.appendChild(option);
});
easings.map(name => {
const option = Object.assign(document.createElement('sl-option'), {
textContent: name,
value: name
});
easingName.appendChild(option);
});
animationName.addEventListener('sl-change', () => (animation.name = animationName.value));
easingName.addEventListener('sl-change', () => (animation.easing = easingName.value));
playbackRate.addEventListener('sl-input', () => (animation.playbackRate = playbackRate.value));
</script>
<style>
.animation-sandbox .box {
width: 100px;
height: 100px;
background-color: var(--sl-color-primary-600);
}
.animation-sandbox .controls {
max-width: 300px;
margin-top: 2rem;
}
.animation-sandbox .controls sl-select {
margin-bottom: 1rem;
}
</style>
```
### Using Intersection Observer
Use an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to control the animation when an element enters or exits the viewport. For example, scroll the box below in and out of your screen. The animation stops when the box exits the viewport and restarts each time it enters the viewport.
```html:preview
<div class="animation-scroll">
<sl-animation name="jackInTheBox" duration="2000" iterations="1"><div class="box"></div></sl-animation>
</div>
<script>
const container = document.querySelector('.animation-scroll');
const animation = container.querySelector('sl-animation');
const box = animation.querySelector('.box');
// Watch for the box to enter and exit the viewport. Note that we're observing the box, not the animation element!
const observer = new IntersectionObserver(entries => {
if (entries[0].isIntersecting) {
// Start the animation when the box enters the viewport
animation.play = true;
} else {
animation.play = false;
animation.currentTime = 0;
}
});
observer.observe(box);
</script>
<style>
.animation-scroll .box {
display: inline-block;
width: 100px;
height: 100px;
background-color: var(--sl-color-primary-600);
}
</style>
```
```jsx:react
import { useEffect, useRef, useState } from 'react';
import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
const css = `
.animation-scroll {
height: calc(100vh + 100px);
}
.animation-scroll .box {
display: inline-block;
width: 100px;
height: 100px;
background-color: var(--sl-color-primary-600);
}
`;
const App = () => {
const animation = useRef(null);
const box = useRef(null);
useEffect(() => {
const observer = new IntersectionObserver(entries => {
if (entries[0].isIntersecting) {
animation.current.play = true;
} else {
animation.current.play = false;
animation.current.currentTime = 0;
}
});
if (box.current) {
observer.observe(box.current);
}
}, [box]);
return (
<>
<div class="animation-scroll">
<SlAnimation ref={animation} name="jackInTheBox" duration={2000} iterations={1}>
<div ref={box} class="box" />
</SlAnimation>
</div>
<style>{css}</style>
</>
);
};
```
### Custom Keyframe Formats
Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) to build custom animations.
```html:preview
<div class="animation-keyframes">
<sl-animation easing="ease-in-out" duration="2000" play>
<div class="box"></div>
</sl-animation>
</div>
<script>
const animation = document.querySelector('.animation-keyframes sl-animation');
animation.keyframes = [
{
offset: 0,
easing: 'cubic-bezier(0.250, 0.460, 0.450, 0.940)',
fillMode: 'both',
transformOrigin: 'center center',
transform: 'rotate(0)'
},
{
offset: 1,
easing: 'cubic-bezier(0.250, 0.460, 0.450, 0.940)',
fillMode: 'both',
transformOrigin: 'center center',
transform: 'rotate(90deg)'
}
];
</script>
<style>
.animation-keyframes .box {
width: 100px;
height: 100px;
background-color: var(--sl-color-primary-600);
}
</style>
```
```jsx:react
import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
const css = `
.animation-keyframes .box {
width: 100px;
height: 100px;
background-color: var(--sl-color-primary-600);
}
`;
const App = () => (
<>
<div class="animation-keyframes">
<SlAnimation
easing="ease-in-out"
duration={2000}
play
keyframes={[
{
offset: 0,
easing: 'cubic-bezier(0.250, 0.460, 0.450, 0.940)',
fillMode: 'both',
transformOrigin: 'center center',
transform: 'rotate(0)'
},
{
offset: 1,
easing: 'cubic-bezier(0.250, 0.460, 0.450, 0.940)',
fillMode: 'both',
transformOrigin: 'center center',
transform: 'rotate(90deg)'
}
]}
>
<div class="box" />
</SlAnimation>
</div>
<style>{css}</style>
</>
);
```
### Playing Animations on Demand
Animations won't play until you apply the `play` attribute. You can omit it initially, then apply it on demand such as after a user interaction. In this example, the button will animate once every time the button is clicked.
```html:preview
<div class="animation-form">
<sl-animation name="rubberBand" duration="1000" iterations="1">
<sl-button variant="primary">Click me</sl-button>
</sl-animation>
</div>
<script>
const container = document.querySelector('.animation-form');
const animation = container.querySelector('sl-animation');
const button = container.querySelector('sl-button');
button.addEventListener('click', () => {
animation.play = true;
});
</script>
```
```jsx:react
import { useState } from 'react';
import { SlAnimation, SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [play, setPlay] = useState(false);
return (
<div class="animation-form">
<SlAnimation name="rubberBand" duration={1000} iterations={1} play={play} onSlFinish={() => setPlay(false)}>
<SlButton variant="primary" onClick={() => setPlay(true)}>
Click me
</SlButton>
</SlAnimation>
</div>
);
};
```

207
docs/pages/components/avatar.md Normal file
View File

@@ -0,0 +1,207 @@
---
meta:
title: Avatar
description: Avatars are used to represent a person or object.
layout: component
---
By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a `label` for assistive devices.
```html:preview
<sl-avatar label="User avatar"></sl-avatar>
```
```jsx:react
import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlAvatar label="User avatar" />;
```
## Examples
### Images
To use an image for the avatar, set the `image` and `label` attributes. This will take priority and be shown over initials and icons.
Avatar images can be lazily loaded by setting the `loading` attribute to `lazy`.
```html:preview
<sl-avatar
image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
label="Avatar of a gray tabby kitten looking down"
></sl-avatar>
<sl-avatar
image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
label="Avatar of a white and grey kitten on grey textile"
loading="lazy"
></sl-avatar>
```
```jsx:react
import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlAvatar
image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
label="Avatar of a gray tabby kitten looking down"
/>
<SlAvatar
image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
label="Avatar of a white and grey kitten on grey textile"
loading="lazy"
/>
);
```
### Initials
When you don't have an image to use, you can set the `initials` attribute to show something more personalized than an icon.
```html:preview
<sl-avatar initials="SL" label="Avatar with initials: SL"></sl-avatar>
```
```jsx:react
import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlAvatar initials="SL" label="Avatar with initials: SL" />;
```
### Custom Icons
When no image or initials are set, an icon will be shown. The default avatar shows a generic "user" icon, but you can customize this with the `icon` slot.
```html:preview
<sl-avatar label="Avatar with an image icon">
<sl-icon slot="icon" name="image"></sl-icon>
</sl-avatar>
<sl-avatar label="Avatar with an archive icon">
<sl-icon slot="icon" name="archive"></sl-icon>
</sl-avatar>
<sl-avatar label="Avatar with a briefcase icon">
<sl-icon slot="icon" name="briefcase"></sl-icon>
</sl-avatar>
```
```jsx:react
import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlAvatar label="Avatar with an image icon">
<SlIcon slot="icon" name="image" />
</SlAvatar>
<SlAvatar label="Avatar with an archive icon">
<SlIcon slot="icon" name="archive" />
</SlAvatar>
<SlAvatar label="Avatar with a briefcase icon">
<SlIcon slot="icon" name="briefcase" />
</SlAvatar>
</>
);
```
### Shapes
Avatars can be shaped using the `shape` attribute.
```html:preview
<sl-avatar shape="square" label="Square avatar"></sl-avatar>
<sl-avatar shape="rounded" label="Rounded avatar"></sl-avatar>
<sl-avatar shape="circle" label="Circle avatar"></sl-avatar>
```
```jsx:react
import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlAvatar shape="square" label="Square avatar" />
<SlAvatar shape="rounded" label="Rounded avatar" />
<SlAvatar shape="circle" label="Circle avatar" />
</>
);
```
### Avatar Groups
You can group avatars with a few lines of CSS.
```html:preview
<div class="avatar-group">
<sl-avatar
image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
label="Avatar 1 of 4"
></sl-avatar>
<sl-avatar
image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
label="Avatar 2 of 4"
></sl-avatar>
<sl-avatar
image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
label="Avatar 3 of 4"
></sl-avatar>
<sl-avatar
image="https://images.unsplash.com/flagged/photo-1554078875-e37cb8b0e27d?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=top&q=80"
label="Avatar 4 of 4"
></sl-avatar>
</div>
<style>
.avatar-group sl-avatar:not(:first-of-type) {
margin-left: -1rem;
}
.avatar-group sl-avatar::part(base) {
border: solid 2px var(--sl-color-neutral-0);
}
</style>
```
```jsx:react
import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
const css = `
.avatar-group sl-avatar:not(:first-of-type) {
margin-left: -1rem;
}
.avatar-group sl-avatar::part(base) {
border: solid 2px var(--sl-color-neutral-0);
}
`;
const App = () => (
<>
<div className="avatar-group">
<SlAvatar
image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
label="Avatar 1 of 4"
/>
<SlAvatar
image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
label="Avatar 2 of 4"
/>
<SlAvatar
image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
label="Avatar 3 of 4"
/>
<SlAvatar
image="https://images.unsplash.com/flagged/photo-1554078875-e37cb8b0e27d?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=top&q=80"
label="Avatar 4 of 4"
/>
</div>
<style>{css}</style>
</>
);
```

230
docs/pages/components/badge.md Normal file
View File

@@ -0,0 +1,230 @@
---
meta:
title: Badge
description: Badges are used to draw attention and display statuses or counts.
layout: component
---
```html:preview
<sl-badge>Badge</sl-badge>
```
```jsx:react
import { SlBadge } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlBadge>Badge</SlBadge>;
```
## Examples
### Variants
Set the `variant` attribute to change the badge's variant.
```html:preview
<sl-badge variant="primary">Primary</sl-badge>
<sl-badge variant="success">Success</sl-badge>
<sl-badge variant="neutral">Neutral</sl-badge>
<sl-badge variant="warning">Warning</sl-badge>
<sl-badge variant="danger">Danger</sl-badge>
```
```jsx:react
import { SlBadge } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlBadge variant="primary">Primary</SlBadge>
<SlBadge variant="success">Success</SlBadge>
<SlBadge variant="neutral">Neutral</SlBadge>
<SlBadge variant="warning">Warning</SlBadge>
<SlBadge variant="danger">Danger</SlBadge>
</>
);
```
### Pill Badges
Use the `pill` attribute to give badges rounded edges.
```html:preview
<sl-badge variant="primary" pill>Primary</sl-badge>
<sl-badge variant="success" pill>Success</sl-badge>
<sl-badge variant="neutral" pill>Neutral</sl-badge>
<sl-badge variant="warning" pill>Warning</sl-badge>
<sl-badge variant="danger" pill>Danger</sl-badge>
```
```jsx:react
import { SlBadge } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlBadge variant="primary" pill>
Primary
</SlBadge>
<SlBadge variant="success" pill>
Success
</SlBadge>
<SlBadge variant="neutral" pill>
Neutral
</SlBadge>
<SlBadge variant="warning" pill>
Warning
</SlBadge>
<SlBadge variant="danger" pill>
Danger
</SlBadge>
</>
);
```
### Pulsating Badges
Use the `pulse` attribute to draw attention to the badge with a subtle animation.
```html:preview
<div class="badge-pulse">
<sl-badge variant="primary" pill pulse>1</sl-badge>
<sl-badge variant="success" pill pulse>1</sl-badge>
<sl-badge variant="neutral" pill pulse>1</sl-badge>
<sl-badge variant="warning" pill pulse>1</sl-badge>
<sl-badge variant="danger" pill pulse>1</sl-badge>
</div>
<style>
.badge-pulse sl-badge:not(:last-of-type) {
margin-right: 1rem;
}
</style>
```
```jsx:react
import { SlBadge } from '@shoelace-style/shoelace/dist/react';
const css = `
.badge-pulse sl-badge:not(:last-of-type) {
margin-right: 1rem;
}
`;
const App = () => (
<>
<div className="badge-pulse">
<SlBadge variant="primary" pill pulse>
1
</SlBadge>
<SlBadge variant="success" pill pulse>
1
</SlBadge>
<SlBadge variant="neutral" pill pulse>
1
</SlBadge>
<SlBadge variant="warning" pill pulse>
1
</SlBadge>
<SlBadge variant="danger" pill pulse>
1
</SlBadge>
</div>
<style>{css}</style>
</>
);
```
### With Buttons
One of the most common use cases for badges is attaching them to buttons. To make this easier, badges will be automatically positioned at the top-right when they're a child of a button.
```html:preview
<sl-button>
Requests
<sl-badge pill>30</sl-badge>
</sl-button>
<sl-button style="margin-inline-start: 1rem;">
Warnings
<sl-badge variant="warning" pill>8</sl-badge>
</sl-button>
<sl-button style="margin-inline-start: 1rem;">
Errors
<sl-badge variant="danger" pill>6</sl-badge>
</sl-button>
```
{% raw %}
```jsx:react
import { SlBadge, SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton>
Requests
<SlBadge pill>30</SlBadge>
</SlButton>
<SlButton style={{ marginInlineStart: '1rem' }}>
Warnings
<SlBadge variant="warning" pill>
8
</SlBadge>
</SlButton>
<SlButton style={{ marginInlineStart: '1rem' }}>
Errors
<SlBadge variant="danger" pill>
6
</SlBadge>
</SlButton>
</>
);
```
{% endraw %}
### With Menu Items
When including badges in menu items, use the `suffix` slot to make sure they're aligned correctly.
```html:preview
<sl-menu style="max-width: 240px;">
<sl-menu-label>Messages</sl-menu-label>
<sl-menu-item>Comments <sl-badge slot="suffix" variant="neutral" pill>4</sl-badge></sl-menu-item>
<sl-menu-item>Replies <sl-badge slot="suffix" variant="neutral" pill>12</sl-badge></sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlBadge, SlButton, SlMenu, SlMenuItem, SlMenuLabel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu
style={{
maxWidth: '240px',
border: 'solid 1px var(--sl-panel-border-color)',
borderRadius: 'var(--sl-border-radius-medium)'
}}
>
<SlMenuLabel>Messages</SlMenuLabel>
<SlMenuItem>
Comments
<SlBadge slot="suffix" variant="neutral" pill>
4
</SlBadge>
</SlMenuItem>
<SlMenuItem>
Replies
<SlBadge slot="suffix" variant="neutral" pill>
12
</SlBadge>
</SlMenuItem>
</SlMenu>
);
```
{% endraw %}

36
docs/pages/components/breadcrumb-item.md Normal file
View File

@@ -0,0 +1,36 @@
---
meta:
title: Breadcrumb Item
description: Breadcrumb Items are used inside breadcrumbs to represent different links.
layout: component
---
```html:preview
<sl-breadcrumb>
<sl-breadcrumb-item>
<sl-icon slot="prefix" name="house"></sl-icon>
Home
</sl-breadcrumb-item>
<sl-breadcrumb-item>Clothing</sl-breadcrumb-item>
<sl-breadcrumb-item>Shirts</sl-breadcrumb-item>
</sl-breadcrumb>
```
```jsx:react
import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlBreadcrumb>
<SlBreadcrumbItem>
<SlIcon slot="prefix" name="house"></SlIcon>
Home
</SlBreadcrumbItem>
<SlBreadcrumbItem>Clothing</SlBreadcrumbItem>
<SlBreadcrumbItem>Shirts</SlBreadcrumbItem>
</SlBreadcrumb>
);
```
:::tip
Additional demonstrations can be found in the [breadcrumb examples](/components/breadcrumb).
:::

251
docs/pages/components/breadcrumb.md Normal file
View File

@@ -0,0 +1,251 @@
---
meta:
title: Breadcrumb
description: Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
layout: component
---
Breadcrumbs are usually placed before a page's main content with the current page shown last to indicate the user's position in the navigation.
```html:preview
<sl-breadcrumb>
<sl-breadcrumb-item>Catalog</sl-breadcrumb-item>
<sl-breadcrumb-item>Clothing</sl-breadcrumb-item>
<sl-breadcrumb-item>Women's</sl-breadcrumb-item>
<sl-breadcrumb-item>Shirts &amp; Tops</sl-breadcrumb-item>
</sl-breadcrumb>
```
```jsx:react
import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlBreadcrumb>
<SlBreadcrumbItem>Catalog</SlBreadcrumbItem>
<SlBreadcrumbItem>Clothing</SlBreadcrumbItem>
<SlBreadcrumbItem>Women's</SlBreadcrumbItem>
<SlBreadcrumbItem>Shirts &amp; Tops</SlBreadcrumbItem>
</SlBreadcrumb>
);
```
## Examples
### Breadcrumb Links
By default, breadcrumb items are rendered as buttons so you can use them to navigate single-page applications. In this case, you'll need to add event listeners to handle clicks.
For websites, you'll probably want to use links instead. You can make any breadcrumb item a link by applying an `href` attribute to it. Now, when the user activates it, they'll be taken to the corresponding page — no event listeners required.
```html:preview
<sl-breadcrumb>
<sl-breadcrumb-item href="https://example.com/home">Homepage</sl-breadcrumb-item>
<sl-breadcrumb-item href="https://example.com/home/services">Our Services</sl-breadcrumb-item>
<sl-breadcrumb-item href="https://example.com/home/services/digital">Digital Media</sl-breadcrumb-item>
<sl-breadcrumb-item href="https://example.com/home/services/digital/web-design">Web Design</sl-breadcrumb-item>
</sl-breadcrumb>
```
```jsx:react
import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlBreadcrumb>
<SlBreadcrumbItem href="https://example.com/home">Homepage</SlBreadcrumbItem>
<SlBreadcrumbItem href="https://example.com/home/services">Our Services</SlBreadcrumbItem>
<SlBreadcrumbItem href="https://example.com/home/services/digital">Digital Media</SlBreadcrumbItem>
<SlBreadcrumbItem href="https://example.com/home/services/digital/web-design">Web Design</SlBreadcrumbItem>
</SlBreadcrumb>
);
```
### Custom Separators
Use the `separator` slot to change the separator that goes between breadcrumb items. Icons work well, but you can also use text or an image.
```html:preview
<sl-breadcrumb>
<sl-icon name="dot" slot="separator"></sl-icon>
<sl-breadcrumb-item>First</sl-breadcrumb-item>
<sl-breadcrumb-item>Second</sl-breadcrumb-item>
<sl-breadcrumb-item>Third</sl-breadcrumb-item>
</sl-breadcrumb>
<br />
<sl-breadcrumb>
<sl-icon name="arrow-right" slot="separator"></sl-icon>
<sl-breadcrumb-item>First</sl-breadcrumb-item>
<sl-breadcrumb-item>Second</sl-breadcrumb-item>
<sl-breadcrumb-item>Third</sl-breadcrumb-item>
</sl-breadcrumb>
<br />
<sl-breadcrumb>
<span slot="separator">/</span>
<sl-breadcrumb-item>First</sl-breadcrumb-item>
<sl-breadcrumb-item>Second</sl-breadcrumb-item>
<sl-breadcrumb-item>Third</sl-breadcrumb-item>
</sl-breadcrumb>
```
```jsx:react
import '@shoelace-style/shoelace/dist/components/icon/icon.js';
import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlBreadcrumb>
<sl-icon name="dot" slot="separator" />
<SlBreadcrumbItem>First</SlBreadcrumbItem>
<SlBreadcrumbItem>Second</SlBreadcrumbItem>
<SlBreadcrumbItem>Third</SlBreadcrumbItem>
</SlBreadcrumb>
<br />
<SlBreadcrumb>
<sl-icon name="arrow-right" slot="separator" />
<SlBreadcrumbItem>First</SlBreadcrumbItem>
<SlBreadcrumbItem>Second</SlBreadcrumbItem>
<SlBreadcrumbItem>Third</SlBreadcrumbItem>
</SlBreadcrumb>
<br />
<SlBreadcrumb>
<span slot="separator">/</span>
<SlBreadcrumbItem>First</SlBreadcrumbItem>
<SlBreadcrumbItem>Second</SlBreadcrumbItem>
<SlBreadcrumbItem>Third</SlBreadcrumbItem>
</SlBreadcrumb>
</>
);
```
### Prefixes
Use the `prefix` slot to add content before any breadcrumb item.
```html:preview
<sl-breadcrumb>
<sl-breadcrumb-item>
<sl-icon slot="prefix" name="house"></sl-icon>
Home
</sl-breadcrumb-item>
<sl-breadcrumb-item>Articles</sl-breadcrumb-item>
<sl-breadcrumb-item>Traveling</sl-breadcrumb-item>
</sl-breadcrumb>
```
```jsx:react
import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlBreadcrumb>
<SlBreadcrumbItem>
<SlIcon slot="prefix" name="house" />
Home
</SlBreadcrumbItem>
<SlBreadcrumbItem>Articles</SlBreadcrumbItem>
<SlBreadcrumbItem>Traveling</SlBreadcrumbItem>
</SlBreadcrumb>
);
```
### Suffixes
Use the `suffix` slot to add content after any breadcrumb item.
```html:preview
<sl-breadcrumb>
<sl-breadcrumb-item>Documents</sl-breadcrumb-item>
<sl-breadcrumb-item>Policies</sl-breadcrumb-item>
<sl-breadcrumb-item>
Security
<sl-icon slot="suffix" name="shield-lock"></sl-icon>
</sl-breadcrumb-item>
</sl-breadcrumb>
```
```jsx:react
import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlBreadcrumb>
<SlBreadcrumbItem>Documents</SlBreadcrumbItem>
<SlBreadcrumbItem>Policies</SlBreadcrumbItem>
<SlBreadcrumbItem>
Security
<SlIcon slot="suffix" name="shield-lock"></SlIcon>
</SlBreadcrumbItem>
</SlBreadcrumb>
);
```
### With Dropdowns
Dropdown menus can be placed in a prefix or suffix slot to provide additional options.
```html:preview
<sl-breadcrumb>
<sl-breadcrumb-item>Homepage</sl-breadcrumb-item>
<sl-breadcrumb-item>Our Services</sl-breadcrumb-item>
<sl-breadcrumb-item>Digital Media</sl-breadcrumb-item>
<sl-breadcrumb-item>
Web Design
<sl-dropdown slot="suffix">
<sl-button slot="trigger" size="small" circle>
<sl-icon label="More options" name="three-dots"></sl-icon>
</sl-button>
<sl-menu>
<sl-menu-item type="checkbox" checked>Web Design</sl-menu-item>
<sl-menu-item type="checkbox">Web Development</sl-menu-item>
<sl-menu-item type="checkbox">Marketing</sl-menu-item>
</sl-menu>
</sl-dropdown>
</sl-breadcrumb-item>
</sl-breadcrumb>
```
```jsx:react
import {
SlBreadcrumb,
SlBreadcrumbItem,
SlButton,
SlDropdown,
SlIcon,
SlMenu,
SlMenuItem
} from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlBreadcrumb>
<SlBreadcrumbItem>Homepage</SlBreadcrumbItem>
<SlBreadcrumbItem>Our Services</SlBreadcrumbItem>
<SlBreadcrumbItem>Digital Media</SlBreadcrumbItem>
<SlBreadcrumbItem>
Web Design
<SlDropdown slot="suffix">
<SlButton slot="trigger" size="small" circle>
<SlIcon label="More options" name="three-dots"></SlIcon>
</SlButton>
<SlMenu>
<SlMenuItem type="checkbox" checked>
Web Design
</SlMenuItem>
<SlMenuItem type="checkbox">Web Development</SlMenuItem>
<SlMenuItem type="checkbox">Marketing</SlMenuItem>
</SlMenu>
</SlDropdown>
</SlBreadcrumbItem>
</SlBreadcrumb>
);
```

494
docs/pages/components/button-group.md Normal file
View File

@@ -0,0 +1,494 @@
---
meta:
title: Button Group
description: Button groups can be used to group related buttons into sections.
layout: component
---
```html:preview
<sl-button-group label="Alignment">
<sl-button>Left</sl-button>
<sl-button>Center</sl-button>
<sl-button>Right</sl-button>
</sl-button-group>
```
```jsx:react
import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlButtonGroup label="Alignment">
<SlButton>Left</SlButton>
<SlButton>Center</SlButton>
<SlButton>Right</SlButton>
</SlButtonGroup>
);
```
## Examples
### Button Sizes
All button sizes are supported, but avoid mixing sizes within the same button group.
```html:preview
<sl-button-group label="Alignment">
<sl-button size="small">Left</sl-button>
<sl-button size="small">Center</sl-button>
<sl-button size="small">Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button size="medium">Left</sl-button>
<sl-button size="medium">Center</sl-button>
<sl-button size="medium">Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button size="large">Left</sl-button>
<sl-button size="large">Center</sl-button>
<sl-button size="large">Right</sl-button>
</sl-button-group>
```
```jsx:react
import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButtonGroup label="Alignment">
<SlButton size="small">Left</SlButton>
<SlButton size="small">Center</SlButton>
<SlButton size="small">Right</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton size="medium">Left</SlButton>
<SlButton size="medium">Center</SlButton>
<SlButton size="medium">Right</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton size="large">Left</SlButton>
<SlButton size="large">Center</SlButton>
<SlButton size="large">Right</SlButton>
</SlButtonGroup>
</>
);
```
### Theme Buttons
Theme buttons are supported through the button's `variant` attribute.
```html:preview
<sl-button-group label="Alignment">
<sl-button variant="primary">Left</sl-button>
<sl-button variant="primary">Center</sl-button>
<sl-button variant="primary">Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button variant="success">Left</sl-button>
<sl-button variant="success">Center</sl-button>
<sl-button variant="success">Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button variant="neutral">Left</sl-button>
<sl-button variant="neutral">Center</sl-button>
<sl-button variant="neutral">Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button variant="warning">Left</sl-button>
<sl-button variant="warning">Center</sl-button>
<sl-button variant="warning">Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button variant="danger">Left</sl-button>
<sl-button variant="danger">Center</sl-button>
<sl-button variant="danger">Right</sl-button>
</sl-button-group>
```
```jsx:react
import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButtonGroup label="Alignment">
<SlButton variant="primary">Left</SlButton>
<SlButton variant="primary">Center</SlButton>
<SlButton variant="primary">Right</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton variant="success">Left</SlButton>
<SlButton variant="success">Center</SlButton>
<SlButton variant="success">Right</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton variant="neutral">Left</SlButton>
<SlButton variant="neutral">Center</SlButton>
<SlButton variant="neutral">Right</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton variant="warning">Left</SlButton>
<SlButton variant="warning">Center</SlButton>
<SlButton variant="warning">Right</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton variant="danger">Left</SlButton>
<SlButton variant="danger">Center</SlButton>
<SlButton variant="danger">Right</SlButton>
</SlButtonGroup>
</>
);
```
### Pill Buttons
Pill buttons are supported through the button's `pill` attribute.
```html:preview
<sl-button-group label="Alignment">
<sl-button size="small" pill>Left</sl-button>
<sl-button size="small" pill>Center</sl-button>
<sl-button size="small" pill>Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button size="medium" pill>Left</sl-button>
<sl-button size="medium" pill>Center</sl-button>
<sl-button size="medium" pill>Right</sl-button>
</sl-button-group>
<br /><br />
<sl-button-group label="Alignment">
<sl-button size="large" pill>Left</sl-button>
<sl-button size="large" pill>Center</sl-button>
<sl-button size="large" pill>Right</sl-button>
</sl-button-group>
```
```jsx:react
import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButtonGroup label="Alignment">
<SlButton size="small" pill>
Left
</SlButton>
<SlButton size="small" pill>
Center
</SlButton>
<SlButton size="small" pill>
Right
</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton size="medium" pill>
Left
</SlButton>
<SlButton size="medium" pill>
Center
</SlButton>
<SlButton size="medium" pill>
Right
</SlButton>
</SlButtonGroup>
<br />
<br />
<SlButtonGroup label="Alignment">
<SlButton size="large" pill>
Left
</SlButton>
<SlButton size="large" pill>
Center
</SlButton>
<SlButton size="large" pill>
Right
</SlButton>
</SlButtonGroup>
</>
);
```
### Dropdowns in Button Groups
Dropdowns can be placed inside button groups as long as the trigger is an `<sl-button>` element.
```html:preview
<sl-button-group label="Example Button Group">
<sl-button>Button</sl-button>
<sl-button>Button</sl-button>
<sl-dropdown>
<sl-button slot="trigger" caret>Dropdown</sl-button>
<sl-menu>
<sl-menu-item>Item 1</sl-menu-item>
<sl-menu-item>Item 2</sl-menu-item>
<sl-menu-item>Item 3</sl-menu-item>
</sl-menu>
</sl-dropdown>
</sl-button-group>
```
```jsx:react
import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlButtonGroup label="Example Button Group">
<SlButton>Button</SlButton>
<SlButton>Button</SlButton>
<SlDropdown>
<SlButton slot="trigger" caret>
Dropdown
</SlButton>
<SlMenu>
<SlMenuItem>Item 1</SlMenuItem>
<SlMenuItem>Item 2</SlMenuItem>
<SlMenuItem>Item 3</SlMenuItem>
</SlMenu>
</SlDropdown>
</SlButtonGroup>
);
```
### Split Buttons
Create a split button using a button and a dropdown. Use a [visually hidden](/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
```html:preview
<sl-button-group label="Example Button Group">
<sl-button variant="primary">Save</sl-button>
<sl-dropdown placement="bottom-end">
<sl-button slot="trigger" variant="primary" caret>
<sl-visually-hidden>More options</sl-visually-hidden>
</sl-button>
<sl-menu>
<sl-menu-item>Save</sl-menu-item>
<sl-menu-item>Save as&hellip;</sl-menu-item>
<sl-menu-item>Save all</sl-menu-item>
</sl-menu>
</sl-dropdown>
</sl-button-group>
```
```jsx:react
import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlButtonGroup label="Example Button Group">
<SlButton variant="primary">Save</SlButton>
<SlDropdown placement="bottom-end">
<SlButton slot="trigger" variant="primary" caret></SlButton>
<SlMenu>
<SlMenuItem>Save</SlMenuItem>
<SlMenuItem>Save as&hellip;</SlMenuItem>
<SlMenuItem>Save all</SlMenuItem>
</SlMenu>
</SlDropdown>
</SlButtonGroup>
);
```
### Tooltips in Button Groups
Buttons can be wrapped in tooltips to provide more detail when the user interacts with them.
```html:preview
<sl-button-group label="Alignment">
<sl-tooltip content="I'm on the left">
<sl-button>Left</sl-button>
</sl-tooltip>
<sl-tooltip content="I'm in the middle">
<sl-button>Center</sl-button>
</sl-tooltip>
<sl-tooltip content="I'm on the right">
<sl-button>Right</sl-button>
</sl-tooltip>
</sl-button-group>
```
```jsx:react
import { SlButton, SlButtonGroup, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButtonGroup label="Alignment">
<SlTooltip content="I'm on the left">
<SlButton>Left</SlButton>
</SlTooltip>
<SlTooltip content="I'm in the middle">
<SlButton>Center</SlButton>
</SlTooltip>
<SlTooltip content="I'm on the right">
<SlButton>Right</SlButton>
</SlTooltip>
</SlButtonGroup>
</>
);
```
### Toolbar Example
Create interactive toolbars with button groups.
```html:preview
<div class="button-group-toolbar">
<sl-button-group label="History">
<sl-tooltip content="Undo">
<sl-button><sl-icon name="arrow-counterclockwise" label="Undo"></sl-icon></sl-button>
</sl-tooltip>
<sl-tooltip content="Redo">
<sl-button><sl-icon name="arrow-clockwise" label="Redo"></sl-icon></sl-button>
</sl-tooltip>
</sl-button-group>
<sl-button-group label="Formatting">
<sl-tooltip content="Bold">
<sl-button><sl-icon name="type-bold" label="Bold"></sl-icon></sl-button>
</sl-tooltip>
<sl-tooltip content="Italic">
<sl-button><sl-icon name="type-italic" label="Italic"></sl-icon></sl-button>
</sl-tooltip>
<sl-tooltip content="Underline">
<sl-button><sl-icon name="type-underline" label="Underline"></sl-icon></sl-button>
</sl-tooltip>
</sl-button-group>
<sl-button-group label="Alignment">
<sl-tooltip content="Align Left">
<sl-button><sl-icon name="justify-left" label="Align Left"></sl-icon></sl-button>
</sl-tooltip>
<sl-tooltip content="Align Center">
<sl-button><sl-icon name="justify" label="Align Center"></sl-icon></sl-button>
</sl-tooltip>
<sl-tooltip content="Align Right">
<sl-button><sl-icon name="justify-right" label="Align Right"></sl-icon></sl-button>
</sl-tooltip>
</sl-button-group>
</div>
<style>
.button-group-toolbar sl-button-group:not(:last-of-type) {
margin-right: var(--sl-spacing-x-small);
}
</style>
```
```jsx:react
import { SlButton, SlButtonGroup, SlIcon, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const css = `
.button-group-toolbar sl-button-group:not(:last-of-type) {
margin-right: var(--sl-spacing-x-small);
}
`;
const App = () => (
<>
<div className="button-group-toolbar">
<SlButtonGroup label="History">
<SlTooltip content="Undo">
<SlButton>
<SlIcon name="arrow-counterclockwise"></SlIcon>
</SlButton>
</SlTooltip>
<SlTooltip content="Redo">
<SlButton>
<SlIcon name="arrow-clockwise"></SlIcon>
</SlButton>
</SlTooltip>
</SlButtonGroup>
<SlButtonGroup label="Formatting">
<SlTooltip content="Bold">
<SlButton>
<SlIcon name="type-bold"></SlIcon>
</SlButton>
</SlTooltip>
<SlTooltip content="Italic">
<SlButton>
<SlIcon name="type-italic"></SlIcon>
</SlButton>
</SlTooltip>
<SlTooltip content="Underline">
<SlButton>
<SlIcon name="type-underline"></SlIcon>
</SlButton>
</SlTooltip>
</SlButtonGroup>
<SlButtonGroup label="Alignment">
<SlTooltip content="Align Left">
<SlButton>
<SlIcon name="justify-left"></SlIcon>
</SlButton>
</SlTooltip>
<SlTooltip content="Align Center">
<SlButton>
<SlIcon name="justify"></SlIcon>
</SlButton>
</SlTooltip>
<SlTooltip content="Align Right">
<SlButton>
<SlIcon name="justify-right"></SlIcon>
</SlButton>
</SlTooltip>
</SlButtonGroup>
</div>
<style>{css}</style>
</>
);
```

543
docs/pages/components/button.md Normal file
View File

@@ -0,0 +1,543 @@
---
meta:
title: Button
description: Buttons represent actions that are available to the user.
layout: component
---
```html:preview
<sl-button>Button</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlButton>Button</SlButton>;
```
## Examples
### Variants
Use the `variant` attribute to set the button's variant.
```html:preview
<sl-button variant="default">Default</sl-button>
<sl-button variant="primary">Primary</sl-button>
<sl-button variant="success">Success</sl-button>
<sl-button variant="neutral">Neutral</sl-button>
<sl-button variant="warning">Warning</sl-button>
<sl-button variant="danger">Danger</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="default">Default</SlButton>
<SlButton variant="primary">Primary</SlButton>
<SlButton variant="success">Success</SlButton>
<SlButton variant="neutral">Neutral</SlButton>
<SlButton variant="warning">Warning</SlButton>
<SlButton variant="danger">Danger</SlButton>
</>
);
```
### Sizes
Use the `size` attribute to change a button's size.
```html:preview
<sl-button size="small">Small</sl-button>
<sl-button size="medium">Medium</sl-button>
<sl-button size="large">Large</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton size="small">Small</SlButton>
<SlButton size="medium">Medium</SlButton>
<SlButton size="large">Large</SlButton>
</>
);
```
### Outline Buttons
Use the `outline` attribute to draw outlined buttons with transparent backgrounds.
```html:preview
<sl-button variant="default" outline>Default</sl-button>
<sl-button variant="primary" outline>Primary</sl-button>
<sl-button variant="success" outline>Success</sl-button>
<sl-button variant="neutral" outline>Neutral</sl-button>
<sl-button variant="warning" outline>Warning</sl-button>
<sl-button variant="danger" outline>Danger</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="default" outline>
Default
</SlButton>
<SlButton variant="primary" outline>
Primary
</SlButton>
<SlButton variant="success" outline>
Success
</SlButton>
<SlButton variant="neutral" outline>
Neutral
</SlButton>
<SlButton variant="warning" outline>
Warning
</SlButton>
<SlButton variant="danger" outline>
Danger
</SlButton>
</>
);
```
### Pill Buttons
Use the `pill` attribute to give buttons rounded edges.
```html:preview
<sl-button size="small" pill>Small</sl-button>
<sl-button size="medium" pill>Medium</sl-button>
<sl-button size="large" pill>Large</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton size="small" pill>
Small
</SlButton>
<SlButton size="medium" pill>
Medium
</SlButton>
<SlButton size="large" pill>
Large
</SlButton>
</>
);
```
### Circle Buttons
Use the `circle` attribute to create circular icon buttons. When this attribute is set, the button expects a single `<sl-icon>` in the default slot.
```html:preview
<sl-button variant="default" size="small" circle>
<sl-icon name="gear" label="Settings"></sl-icon>
</sl-button>
<sl-button variant="default" size="medium" circle>
<sl-icon name="gear" label="Settings"></sl-icon>
</sl-button>
<sl-button variant="default" size="large" circle>
<sl-icon name="gear" label="Settings"></sl-icon>
</sl-button>
```
```jsx:react
import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="default" size="small" circle>
<SlIcon name="gear" />
</SlButton>
<SlButton variant="default" size="medium" circle>
<SlIcon name="gear" />
</SlButton>
<SlButton variant="default" size="large" circle>
<SlIcon name="gear" />
</SlButton>
</>
);
```
### Text Buttons
Use the `text` variant to create text buttons that share the same size as regular buttons but don't have backgrounds or borders.
```html:preview
<sl-button variant="text" size="small">Text</sl-button>
<sl-button variant="text" size="medium">Text</sl-button>
<sl-button variant="text" size="large">Text</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="text" size="small">
Text
</SlButton>
<SlButton variant="text" size="medium">
Text
</SlButton>
<SlButton variant="text" size="large">
Text
</SlButton>
</>
);
```
### Link Buttons
It's often helpful to have a button that works like a link. This is possible by setting the `href` attribute, which will make the component render an `<a>` under the hood. This gives you all the default link behavior the browser provides (e.g. [[CMD/CTRL/SHIFT]] + [[CLICK]]) and exposes the `target` and `download` attributes.
```html:preview
<sl-button href="https://example.com/">Link</sl-button>
<sl-button href="https://example.com/" target="_blank">New Window</sl-button>
<sl-button href="/assets/images/wordmark.svg" download="shoelace.svg">Download</sl-button>
<sl-button href="https://example.com/" disabled>Disabled</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton href="https://example.com/">Link</SlButton>
<SlButton href="https://example.com/" target="_blank">
New Window
</SlButton>
<SlButton href="/assets/images/wordmark.svg" download="shoelace.svg">
Download
</SlButton>
<SlButton href="https://example.com/" disabled>
Disabled
</SlButton>
</>
);
```
:::tip
When a `target` is set, the link will receive `rel="noreferrer noopener"` for [security reasons](https://mathiasbynens.github.io/rel-noopener/).
:::
### Setting a Custom Width
As expected, buttons can be given a custom width by setting the `width` attribute. This is useful for making buttons span the full width of their container on smaller screens.
```html:preview
<sl-button variant="default" size="small" style="width: 100%; margin-bottom: 1rem;">Small</sl-button>
<sl-button variant="default" size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</sl-button>
<sl-button variant="default" size="large" style="width: 100%;">Large</sl-button>
```
{% raw %}
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="default" size="small" style={{ width: '100%', marginBottom: '1rem' }}>
Small
</SlButton>
<SlButton variant="default" size="medium" style={{ width: '100%', marginBottom: '1rem' }}>
Medium
</SlButton>
<SlButton variant="default" size="large" style={{ width: '100%' }}>
Large
</SlButton>
</>
);
```
{% endraw %}
### Prefix and Suffix Icons
Use the `prefix` and `suffix` slots to add icons.
```html:preview
<sl-button variant="default" size="small">
<sl-icon slot="prefix" name="gear"></sl-icon>
Settings
</sl-button>
<sl-button variant="default" size="small">
<sl-icon slot="suffix" name="arrow-counterclockwise"></sl-icon>
Refresh
</sl-button>
<sl-button variant="default" size="small">
<sl-icon slot="prefix" name="link-45deg"></sl-icon>
<sl-icon slot="suffix" name="box-arrow-up-right"></sl-icon>
Open
</sl-button>
<br /><br />
<sl-button variant="default">
<sl-icon slot="prefix" name="gear"></sl-icon>
Settings
</sl-button>
<sl-button variant="default">
<sl-icon slot="suffix" name="arrow-counterclockwise"></sl-icon>
Refresh
</sl-button>
<sl-button variant="default">
<sl-icon slot="prefix" name="link-45deg"></sl-icon>
<sl-icon slot="suffix" name="box-arrow-up-right"></sl-icon>
Open
</sl-button>
<br /><br />
<sl-button variant="default" size="large">
<sl-icon slot="prefix" name="gear"></sl-icon>
Settings
</sl-button>
<sl-button variant="default" size="large">
<sl-icon slot="suffix" name="arrow-counterclockwise"></sl-icon>
Refresh
</sl-button>
<sl-button variant="default" size="large">
<sl-icon slot="prefix" name="link-45deg"></sl-icon>
<sl-icon slot="suffix" name="box-arrow-up-right"></sl-icon>
Open
</sl-button>
```
```jsx:react
import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="default" size="small">
<SlIcon slot="prefix" name="gear"></SlIcon>
Settings
</SlButton>
<SlButton variant="default" size="small">
<SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
Refresh
</SlButton>
<SlButton variant="default" size="small">
<SlIcon slot="prefix" name="link-45deg"></SlIcon>
<SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
Open
</SlButton>
<br />
<br />
<SlButton variant="default">
<SlIcon slot="prefix" name="gear"></SlIcon>
Settings
</SlButton>
<SlButton variant="default">
<SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
Refresh
</SlButton>
<SlButton variant="default">
<SlIcon slot="prefix" name="link-45deg"></SlIcon>
<SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
Open
</SlButton>
<br />
<br />
<SlButton variant="default" size="large">
<SlIcon slot="prefix" name="gear"></SlIcon>
Settings
</SlButton>
<SlButton variant="default" size="large">
<SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
Refresh
</SlButton>
<SlButton variant="default" size="large">
<SlIcon slot="prefix" name="link-45deg"></SlIcon>
<SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
Open
</SlButton>
</>
);
```
### Caret
Use the `caret` attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or popover.
```html:preview
<sl-button size="small" caret>Small</sl-button>
<sl-button size="medium" caret>Medium</sl-button>
<sl-button size="large" caret>Large</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton size="small" caret>
Small
</SlButton>
<SlButton size="medium" caret>
Medium
</SlButton>
<SlButton size="large" caret>
Large
</SlButton>
</>
);
```
### Loading
Use the `loading` attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around. Clicks will be suppressed until the loading state is removed.
```html:preview
<sl-button variant="default" loading>Default</sl-button>
<sl-button variant="primary" loading>Primary</sl-button>
<sl-button variant="success" loading>Success</sl-button>
<sl-button variant="neutral" loading>Neutral</sl-button>
<sl-button variant="warning" loading>Warning</sl-button>
<sl-button variant="danger" loading>Danger</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="default" loading>
Default
</SlButton>
<SlButton variant="primary" loading>
Primary
</SlButton>
<SlButton variant="success" loading>
Success
</SlButton>
<SlButton variant="neutral" loading>
Neutral
</SlButton>
<SlButton variant="warning" loading>
Warning
</SlButton>
<SlButton variant="danger" loading>
Danger
</SlButton>
</>
);
```
### Disabled
Use the `disabled` attribute to disable a button. Clicks will be suppressed until the disabled state is removed.
```html:preview
<sl-button variant="default" disabled>Default</sl-button>
<sl-button variant="primary" disabled>Primary</sl-button>
<sl-button variant="success" disabled>Success</sl-button>
<sl-button variant="neutral" disabled>Neutral</sl-button>
<sl-button variant="warning" disabled>Warning</sl-button>
<sl-button variant="danger" disabled>Danger</sl-button>
```
```jsx:react
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlButton variant="default" disabled>
Default
</SlButton>
<SlButton variant="primary" disabled>
Primary
</SlButton>
<SlButton variant="success" disabled>
Success
</SlButton>
<SlButton variant="neutral" disabled>
Neutral
</SlButton>
<SlButton variant="warning" disabled>
Warning
</SlButton>
<SlButton variant="danger" disabled>
Danger
</SlButton>
</>
);
```
### Styling Buttons
This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button's `variant` attribute instead of a class (e.g. `sl-button[variant="primary"]`).
```html:preview
<sl-button class="pink">Pink Button</sl-button>
<style>
sl-button.pink::part(base) {
/* Set design tokens for height and border width */
--sl-input-height-medium: 48px;
--sl-input-border-width: 4px;
border-radius: 0;
background-color: #ff1493;
border-top-color: #ff7ac1;
border-left-color: #ff7ac1;
border-bottom-color: #ad005c;
border-right-color: #ad005c;
color: white;
font-size: 1.125rem;
box-shadow: 0 2px 10px #0002;
transition: var(--sl-transition-medium) transform ease, var(--sl-transition-medium) border ease;
}
sl-button.pink::part(base):hover {
transform: scale(1.05) rotate(-1deg);
}
sl-button.pink::part(base):active {
border-top-color: #ad005c;
border-right-color: #ff7ac1;
border-bottom-color: #ff7ac1;
border-left-color: #ad005c;
transform: scale(1.05) rotate(-1deg) translateY(2px);
}
sl-button.pink::part(base):focus-visible {
outline: dashed 2px deeppink;
outline-offset: 4px;
}
</style>
```

302
docs/pages/components/card.md Normal file
View File

@@ -0,0 +1,302 @@
---
meta:
title: Card
description: Cards can be used to group related subjects in a container.
layout: component
---
```html:preview
<sl-card class="card-overview">
<img
slot="image"
src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
alt="A kitten sits patiently between a terracotta pot and decorative grasses."
/>
<strong>Mittens</strong><br />
This kitten is as cute as he is playful. Bring him home today!<br />
<small>6 weeks old</small>
<div slot="footer">
<sl-button variant="primary" pill>More Info</sl-button>
<sl-rating></sl-rating>
</div>
</sl-card>
<style>
.card-overview {
max-width: 300px;
}
.card-overview small {
color: var(--sl-color-neutral-500);
}
.card-overview [slot='footer'] {
display: flex;
justify-content: space-between;
align-items: center;
}
</style>
```
```jsx:react
import { SlButton, SlCard, SlRating } from '@shoelace-style/shoelace/dist/react';
const css = `
.card-overview {
max-width: 300px;
}
.card-overview small {
color: var(--sl-color-neutral-500);
}
.card-overview [slot="footer"] {
display: flex;
justify-content: space-between;
align-items: center;
}
`;
const App = () => (
<>
<SlCard className="card-overview">
<img
slot="image"
src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
alt="A kitten sits patiently between a terracotta pot and decorative grasses."
/>
<strong>Mittens</strong>
<br />
This kitten is as cute as he is playful. Bring him home today!
<br />
<small>6 weeks old</small>
<div slot="footer">
<SlButton variant="primary" pill>
More Info
</SlButton>
<SlRating></SlRating>
</div>
</SlCard>
<style>{css}</style>
</>
);
```
## Examples
### Basic Card
Basic cards aren't very exciting, but they can display any content you want them to.
```html:preview
<sl-card class="card-basic">
This is just a basic card. No image, no header, and no footer. Just your content.
</sl-card>
<style>
.card-basic {
max-width: 300px;
}
</style>
```
```jsx:react
import { SlCard } from '@shoelace-style/shoelace/dist/react';
const css = `
.card-basic {
max-width: 300px;
}
`;
const App = () => (
<>
<SlCard className="card-basic">
This is just a basic card. No image, no header, and no footer. Just your content.
</SlCard>
<style>{css}</style>
</>
);
```
### Card with Header
Headers can be used to display titles and more.
```html:preview
<sl-card class="card-header">
<div slot="header">
Header Title
<sl-icon-button name="gear" label="Settings"></sl-icon-button>
</div>
This card has a header. You can put all sorts of things in it!
</sl-card>
<style>
.card-header {
max-width: 300px;
}
.card-header [slot='header'] {
display: flex;
align-items: center;
justify-content: space-between;
}
.card-header h3 {
margin: 0;
}
.card-header sl-icon-button {
font-size: var(--sl-font-size-medium);
}
</style>
```
```jsx:react
import { SlCard, SlIconButton } from '@shoelace-style/shoelace/dist/react';
const css = `
.card-header {
max-width: 300px;
}
.card-header [slot="header"] {
display: flex;
align-items: center;
justify-content: space-between;
}
.card-header h3 {
margin: 0;
}
.card-header sl-icon-button {
font-size: var(--sl-font-size-medium);
}
`;
const App = () => (
<>
<SlCard className="card-header">
<div slot="header">
Header Title
<SlIconButton name="gear"></SlIconButton>
</div>
This card has a header. You can put all sorts of things in it!
</SlCard>
<style>{css}</style>
</>
);
```
### Card with Footer
Footers can be used to display actions, summaries, or other relevant content.
```html:preview
<sl-card class="card-footer">
This card has a footer. You can put all sorts of things in it!
<div slot="footer">
<sl-rating></sl-rating>
<sl-button variant="primary">Preview</sl-button>
</div>
</sl-card>
<style>
.card-footer {
max-width: 300px;
}
.card-footer [slot='footer'] {
display: flex;
justify-content: space-between;
align-items: center;
}
</style>
```
```jsx:react
import { SlButton, SlCard, SlRating } from '@shoelace-style/shoelace/dist/react';
const css = `
.card-footer {
max-width: 300px;
}
.card-footer [slot="footer"] {
display: flex;
justify-content: space-between;
align-items: center;
}
`;
const App = () => (
<>
<SlCard className="card-footer">
This card has a footer. You can put all sorts of things in it!
<div slot="footer">
<SlRating></SlRating>
<SlButton slot="footer" variant="primary">
Preview
</SlButton>
</div>
</SlCard>
<style>{css}</style>
</>
);
```
### Images
Cards accept an `image` slot. The image is displayed atop the card and stretches to fit.
```html:preview
<sl-card class="card-image">
<img
slot="image"
src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80"
alt="A kitten walks towards camera on top of pallet."
/>
This is a kitten, but not just any kitten. This kitten likes walking along pallets.
</sl-card>
<style>
.card-image {
max-width: 300px;
}
</style>
```
```jsx:react
import { SlCard } from '@shoelace-style/shoelace/dist/react';
const css = `
.card-image {
max-width: 300px;
}
`;
const App = () => (
<>
<SlCard className="card-image">
<img
slot="image"
src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80"
alt="A kitten walks towards camera on top of pallet."
/>
This is a kitten, but not just any kitten. This kitten likes walking along pallets.
</SlCard>
<style>{css}</style>
</>
);
```

84
docs/pages/components/carousel-item.md Normal file
View File

@@ -0,0 +1,84 @@
---
meta:
title: Carousel Item
description: A carousel item represent a slide within a carousel.
layout: component
---
```html:preview
<sl-carousel pagination>
<sl-carousel-item>
<img
alt="The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash"
src="/assets/examples/carousel/mountains.jpg"
/>
</sl-carousel-item>
<sl-carousel-item>
<img
alt="A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash"
src="/assets/examples/carousel/waterfall.jpg"
/>
</sl-carousel-item>
<sl-carousel-item>
<img
alt="The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash"
src="/assets/examples/carousel/sunset.jpg"
/>
</sl-carousel-item>
<sl-carousel-item>
<img
alt="A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash"
src="/assets/examples/carousel/field.jpg"
/>
</sl-carousel-item>
<sl-carousel-item>
<img
alt="A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash"
src="/assets/examples/carousel/valley.jpg"
/>
</sl-carousel-item>
</sl-carousel>
```
```jsx:react
import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlCarousel pagination>
<SlCarouselItem>
<img
alt="The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash"
src="/assets/examples/carousel/mountains.jpg"
/>
</SlCarouselItem>
<SlCarouselItem>
<img
alt="A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash"
src="/assets/examples/carousel/waterfall.jpg"
/>
</SlCarouselItem>
<SlCarouselItem>
<img
alt="The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash"
src="/assets/examples/carousel/sunset.jpg"
/>
</SlCarouselItem>
<SlCarouselItem>
<img
alt="A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash"
src="/assets/examples/carousel/field.jpg"
/>
</SlCarouselItem>
<SlCarouselItem>
<img
alt="A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash"
src="/assets/examples/carousel/valley.jpg"
/>
</SlCarouselItem>
</SlCarousel>
);
```
:::tip
Additional demonstrations can be found in the [carousel examples](/components/carousel).
:::

1238
docs/pages/components/carousel.md Normal file
View File

File diff suppressed because it is too large Load Diff

163
docs/pages/components/checkbox.md Normal file
View File

@@ -0,0 +1,163 @@
---
meta:
title: Checkbox
description: Checkboxes allow the user to toggle an option on or off.
layout: component
---
```html:preview
<sl-checkbox>Checkbox</sl-checkbox>
```
```jsx:react
import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlCheckbox>Checkbox</SlCheckbox>;
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Checked
Use the `checked` attribute to activate the checkbox.
```html:preview
<sl-checkbox checked>Checked</sl-checkbox>
```
```jsx:react
import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlCheckbox checked>Checked</SlCheckbox>;
```
### Indeterminate
Use the `indeterminate` attribute to make the checkbox indeterminate.
```html:preview
<sl-checkbox indeterminate>Indeterminate</sl-checkbox>
```
```jsx:react
import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlCheckbox indeterminate>Indeterminate</SlCheckbox>;
```
### Disabled
Use the `disabled` attribute to disable the checkbox.
```html:preview
<sl-checkbox disabled>Disabled</sl-checkbox>
```
```jsx:react
import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlCheckbox disabled>Disabled</SlCheckbox>;
```
### Sizes
Use the `size` attribute to change a checkbox's size.
```html:preview
<sl-checkbox size="small">Small</sl-checkbox>
<br />
<sl-checkbox size="medium">Medium</sl-checkbox>
<br />
<sl-checkbox size="large">Large</sl-checkbox>
```
```jsx:react
import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlCheckbox size="small">Small</SlCheckbox>
<br />
<SlCheckbox size="medium">Medium</SlCheckbox>
<br />
<SlCheckbox size="large">Large</SlCheckbox>
</>
);
```
### Custom Validity
Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
```html:preview
<form class="custom-validity">
<sl-checkbox>Check me</sl-checkbox>
<br />
<sl-button type="submit" variant="primary" style="margin-top: 1rem;">Submit</sl-button>
</form>
<script>
const form = document.querySelector('.custom-validity');
const checkbox = form.querySelector('sl-checkbox');
const errorMessage = `Don't forget to check me!`;
// Set initial validity as soon as the element is defined
customElements.whenDefined('sl-checkbox').then(async () => {
await checkbox.updateComplete;
checkbox.setCustomValidity(errorMessage);
});
// Update validity on change
checkbox.addEventListener('sl-change', () => {
checkbox.setCustomValidity(checkbox.checked ? '' : errorMessage);
});
// Handle submit
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
</script>
```
{% raw %}
```jsx:react
import { useEffect, useRef } from 'react';
import { SlButton, SlCheckbox } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const checkbox = useRef(null);
const errorMessage = `Don't forget to check me!`;
function handleChange() {
checkbox.current.setCustomValidity(checkbox.current.checked ? '' : errorMessage);
}
function handleSubmit(event) {
event.preventDefault();
alert('All fields are valid!');
}
useEffect(() => {
checkbox.current.setCustomValidity(errorMessage);
}, []);
return (
<form class="custom-validity" onSubmit={handleSubmit}>
<SlCheckbox ref={checkbox} onSlChange={handleChange}>
Check me
</SlCheckbox>
<br />
<SlButton type="submit" variant="primary" style={{ marginTop: '1rem' }}>
Submit
</SlButton>
</form>
);
};
```
{% endraw %}

140
docs/pages/components/color-picker.md Normal file
View File

@@ -0,0 +1,140 @@
---
meta:
title: Color Picker
description: Color pickers allow the user to select a color.
layout: component
---
```html:preview
<sl-color-picker label="Select a color"></sl-color-picker>
```
```jsx:react
import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlColorPicker label="Select a color" />;
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Initial Value
Use the `value` attribute to set an initial value for the color picker.
```html:preview
<sl-color-picker value="#4a90e2" label="Select a color"></sl-color-picker>
```
```jsx:react
import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlColorPicker value="#4a90e2" label="Select a color" />;
```
### Opacity
Use the `opacity` attribute to enable the opacity slider. When this is enabled, the value will be displayed as HEXA, RGBA, HSLA, or HSVA based on `format`.
```html:preview
<sl-color-picker value="#f5a623ff" opacity label="Select a color"></sl-color-picker>
```
```jsx:react
import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlColorPicker opacity label="Select a color" />;
```
### Formats
Set the color picker's format with the `format` attribute. Valid options include `hex`, `rgb`, `hsl`, and `hsv`. Note that the color picker's input will accept any parsable format (including CSS color names) regardless of this option.
To prevent users from toggling the format themselves, add the `no-format-toggle` attribute.
```html:preview
<sl-color-picker format="hex" value="#4a90e2" label="Select a color"></sl-color-picker>
<sl-color-picker format="rgb" value="rgb(80, 227, 194)" label="Select a color"></sl-color-picker>
<sl-color-picker format="hsl" value="hsl(290, 87%, 47%)" label="Select a color"></sl-color-picker>
<sl-color-picker format="hsv" value="hsv(55, 89%, 97%)" label="Select a color"></sl-color-picker>
```
```jsx:react
import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlColorPicker format="hex" value="#4a90e2" />
<SlColorPicker format="rgb" value="rgb(80, 227, 194)" />
<SlColorPicker format="hsl" value="hsl(290, 87%, 47%)" />
<SlColorPicker format="hsv" value="hsv(55, 89%, 97%)" />
</>
);
```
### Swatches
Use the `swatches` attribute to add convenient presets to the color picker. Any format the color picker can parse is acceptable (including CSS color names), but each value must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values to this property using JavaScript.
```html:preview
<sl-color-picker
label="Select a color"
swatches="
#d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe;
#4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
"
></sl-color-picker>
```
```jsx:react
import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlColorPicker
label="Select a color"
swatches="
#d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe;
#4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
"
/>
);
```
### Sizes
Use the `size` attribute to change the color picker's trigger size.
```html:preview
<sl-color-picker size="small" label="Select a color"></sl-color-picker>
<sl-color-picker size="medium" label="Select a color"></sl-color-picker>
<sl-color-picker size="large" label="Select a color"></sl-color-picker>
```
```jsx:react
import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlColorPicker size="small" label="Select a color" />
<SlColorPicker size="medium" label="Select a color" />
<SlColorPicker size="large" label="Select a color" />
</>
);
```
### Inline
The color picker can be rendered inline instead of in a dropdown using the `inline` attribute.
```html:preview
<sl-color-picker inline label="Select a color"></sl-color-picker>
```
```jsx:react
import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlColorPicker inline label="Select a color" />;
```

134
docs/pages/components/details.md Normal file
View File

@@ -0,0 +1,134 @@
---
meta:
title: Details
description: Details show a brief summary and expand to show additional content.
layout: component
---
<!-- cspell:dictionaries lorem-ipsum -->
```html:preview
<sl-details summary="Toggle Me">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</sl-details>
```
```jsx:react
import { SlDetails } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlDetails summary="Toggle Me">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</SlDetails>
);
```
## Examples
### Disabled
Use the `disable` attribute to prevent the details from expanding.
```html:preview
<sl-details summary="Disabled" disabled>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</sl-details>
```
```jsx:react
import { SlDetails } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlDetails summary="Disabled" disabled>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</SlDetails>
);
```
### Customizing the Summary Icon
Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `summary-icon` part as shown below.
```html:preview
<sl-details summary="Toggle Me" class="custom-icons">
<sl-icon name="plus-square" slot="expand-icon"></sl-icon>
<sl-icon name="dash-square" slot="collapse-icon"></sl-icon>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</sl-details>
<style>
sl-details.custom-icons::part(summary-icon) {
/* Disable the expand/collapse animation */
rotate: none;
}
</style>
```
```jsx:react
import { SlDetails, SlIcon } from '@shoelace-style/shoelace/dist/react';
const css = `
sl-details.custom-icon::part(summary-icon) {
/* Disable the expand/collapse animation */
rotate: none;
}
`;
const App = () => (
<>
<SlDetails summary="Toggle Me" class="custom-icon">
<SlIcon name="plus-square" slot="expand-icon" />
<SlIcon name="dash-square" slot="collapse-icon" />
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.
</SlDetails>
<style>{css}</style>
</>
);
```
### Grouping Details
Details are designed to function independently, but you can simulate a group or "accordion" where only one is shown at a time by listening for the `sl-show` event.
```html:preview
<div class="details-group-example">
<sl-details summary="First" open>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</sl-details>
<sl-details summary="Second">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</sl-details>
<sl-details summary="Third">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</sl-details>
</div>
<script>
const container = document.querySelector('.details-group-example');
// Close all other details when one is shown
container.addEventListener('sl-show', event => {
[...container.querySelectorAll('sl-details')].map(details => (details.open = event.target === details));
});
</script>
<style>
.details-group-example sl-details:not(:last-of-type) {
margin-bottom: var(--sl-spacing-2x-small);
}
</style>
```

321
docs/pages/components/dialog.md Normal file
View File

@@ -0,0 +1,321 @@
---
meta:
title: Dialog
description: 'Dialogs, sometimes called "modals", appear above the page and require the user''s immediate attention.'
layout: component
---
<!-- cspell:dictionaries lorem-ipsum -->
```html:preview
<sl-dialog label="Dialog" class="dialog-overview">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-dialog>
<sl-button>Open Dialog</sl-button>
<script>
const dialog = document.querySelector('.dialog-overview');
const openButton = dialog.nextElementSibling;
const closeButton = dialog.querySelector('sl-button[slot="footer"]');
openButton.addEventListener('click', () => dialog.show());
closeButton.addEventListener('click', () => dialog.hide());
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDialog>
<SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
</>
);
};
```
## Examples
### Custom Width
Use the `--width` custom property to set the dialog's width.
```html:preview
<sl-dialog label="Dialog" class="dialog-width" style="--width: 50vw;">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-dialog>
<sl-button>Open Dialog</sl-button>
<script>
const dialog = document.querySelector('.dialog-width');
const openButton = dialog.nextElementSibling;
const closeButton = dialog.querySelector('sl-button[slot="footer"]');
openButton.addEventListener('click', () => dialog.show());
closeButton.addEventListener('click', () => dialog.hide());
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDialog label="Dialog" open={open} style={{ '--width': '50vw' }} onSlAfterHide={() => setOpen(false)}>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDialog>
<SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
</>
);
};
```
{% endraw %}
### Scrolling
By design, a dialog's height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user.
```html:preview
<sl-dialog label="Dialog" class="dialog-scrolling">
<div style="height: 150vh; border: dashed 2px var(--sl-color-neutral-200); padding: 0 1rem;">
<p>Scroll down and give it a try! 👇</p>
</div>
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-dialog>
<sl-button>Open Dialog</sl-button>
<script>
const dialog = document.querySelector('.dialog-scrolling');
const openButton = dialog.nextElementSibling;
const closeButton = dialog.querySelector('sl-button[slot="footer"]');
openButton.addEventListener('click', () => dialog.show());
closeButton.addEventListener('click', () => dialog.hide());
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
<div
style={{
height: '150vh',
border: 'dashed 2px var(--sl-color-neutral-200)',
padding: '0 1rem'
}}
>
<p>Scroll down and give it a try! 👇</p>
</div>
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDialog>
<SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
</>
);
};
```
{% endraw %}
### Header Actions
The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
```html:preview
<sl-dialog label="Dialog" class="dialog-header-actions">
<sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-dialog>
<sl-button>Open Dialog</sl-button>
<script>
const dialog = document.querySelector('.dialog-header-actions');
const openButton = dialog.nextElementSibling;
const closeButton = dialog.querySelector('sl-button[slot="footer"]');
const newWindowButton = dialog.querySelector('.new-window');
openButton.addEventListener('click', () => dialog.show());
closeButton.addEventListener('click', () => dialog.hide());
newWindowButton.addEventListener('click', () => window.open(location.href));
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDialog, SlIconButton } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
<SlIconButton
class="new-window"
slot="header-actions"
name="box-arrow-up-right"
onClick={() => window.open(location.href)}
/>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDialog>
<SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
</>
);
};
```
### Preventing the Dialog from Closing
By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the [[Escape]] key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
To keep the dialog open in such cases, you can cancel the `sl-request-close` event. When canceled, the dialog will remain open and pulse briefly to draw the user's attention to it.
You can use `event.detail.source` to determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
```html:preview
<sl-dialog label="Dialog" class="dialog-deny-close">
This dialog will not close when you click on the overlay.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-dialog>
<sl-button>Open Dialog</sl-button>
<script>
const dialog = document.querySelector('.dialog-deny-close');
const openButton = dialog.nextElementSibling;
const closeButton = dialog.querySelector('sl-button[slot="footer"]');
openButton.addEventListener('click', () => dialog.show());
closeButton.addEventListener('click', () => dialog.hide());
// Prevent the dialog from closing when the user clicks on the overlay
dialog.addEventListener('sl-request-close', event => {
if (event.detail.source === 'overlay') {
event.preventDefault();
}
});
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
// Prevent the dialog from closing when the user clicks on the overlay
function handleRequestClose(event) {
if (event.detail.source === 'overlay') {
event.preventDefault();
}
}
return (
<>
<SlDialog label="Dialog" open={open} onSlRequestClose={handleRequestClose} onSlAfterHide={() => setOpen(false)}>
This dialog will not close when you click on the overlay.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDialog>
<SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
</>
);
};
```
### Customizing Initial Focus
By default, the dialog's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the dialog. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
```html:preview
<sl-dialog label="Dialog" class="dialog-focus">
<sl-input autofocus placeholder="I will have focus when the dialog is opened"></sl-input>
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-dialog>
<sl-button>Open Dialog</sl-button>
<script>
const dialog = document.querySelector('.dialog-focus');
const input = dialog.querySelector('sl-input');
const openButton = dialog.nextElementSibling;
const closeButton = dialog.querySelector('sl-button[slot="footer"]');
openButton.addEventListener('click', () => dialog.show());
closeButton.addEventListener('click', () => dialog.hide());
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDialog, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
<SlInput autofocus placeholder="I will have focus when the dialog is opened" />
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDialog>
<SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
</>
);
};
```
:::tip
You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
:::

156
docs/pages/components/divider.md Normal file
View File

@@ -0,0 +1,156 @@
---
meta:
title: Divider
description: Dividers are used to visually separate or group elements.
layout: component
---
```html:preview
<sl-divider></sl-divider>
```
```jsx:react
import { SlDivider } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlDivider />;
```
## Examples
### Width
Use the `--width` custom property to change the width of the divider.
```html:preview
<sl-divider style="--width: 4px;"></sl-divider>
```
{% raw %}
```jsx:react
import { SlDivider } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlDivider style={{ '--width': '4px' }} />;
```
{% endraw %}
### Color
Use the `--color` custom property to change the color of the divider.
```html:preview
<sl-divider style="--color: tomato;"></sl-divider>
```
{% raw %}
```jsx:react
import { SlDivider } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlDivider style={{ '--color': 'tomato' }} />;
```
{% endraw %}
### Spacing
Use the `--spacing` custom property to change the amount of space between the divider and it's neighboring elements.
```html:preview
<div style="text-align: center;">
Above
<sl-divider style="--spacing: 2rem;"></sl-divider>
Below
</div>
```
{% raw %}
```jsx:react
import { SlDivider } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
Above
<SlDivider style={{ '--spacing': '2rem' }} />
Below
</>
);
```
{% endraw %}
### Vertical
Add the `vertical` attribute to draw the divider in a vertical orientation. The divider will span the full height of its container. Vertical dividers work especially well inside of a flex container.
```html:preview
<div style="display: flex; align-items: center; height: 2rem;">
First
<sl-divider vertical></sl-divider>
Middle
<sl-divider vertical></sl-divider>
Last
</div>
```
{% raw %}
```jsx:react
import { SlDivider } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<div
style={{
display: 'flex',
alignItems: 'center',
height: '2rem'
}}
>
First
<SlDivider vertical />
Middle
<SlDivider vertical />
Last
</div>
);
```
{% endraw %}
### Menu Dividers
Use dividers in [menus](/components/menu) to visually group menu items.
```html:preview
<sl-menu style="max-width: 200px;">
<sl-menu-item value="1">Option 1</sl-menu-item>
<sl-menu-item value="2">Option 2</sl-menu-item>
<sl-menu-item value="3">Option 3</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item value="4">Option 4</sl-menu-item>
<sl-menu-item value="5">Option 5</sl-menu-item>
<sl-menu-item value="6">Option 6</sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlDivider, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu style={{ maxWidth: '200px' }}>
<SlMenuItem value="1">Option 1</SlMenuItem>
<SlMenuItem value="2">Option 2</SlMenuItem>
<SlMenuItem value="3">Option 3</SlMenuItem>
<sl-divider />
<SlMenuItem value="4">Option 4</SlMenuItem>
<SlMenuItem value="5">Option 5</SlMenuItem>
<SlMenuItem value="6">Option 6</SlMenuItem>
</SlMenu>
);
```
{% endraw %}

522
docs/pages/components/drawer.md Normal file
View File

@@ -0,0 +1,522 @@
---
meta:
title: Drawer
description: Drawers slide in from a container to expose additional options and information.
layout: component
---
<!-- cspell:dictionaries lorem-ipsum -->
```html:preview
<sl-drawer label="Drawer" class="drawer-overview">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-overview');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
## Examples
### Slide in From Start
By default, drawers slide in from the end. To make the drawer slide in from the start, set the `placement` attribute to `start`.
```html:preview
<sl-drawer label="Drawer" placement="start" class="drawer-placement-start">
This drawer slides in from the start.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-placement-start');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" placement="start" open={open} onSlAfterHide={() => setOpen(false)}>
This drawer slides in from the start.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
### Slide in From Top
To make the drawer slide in from the top, set the `placement` attribute to `top`.
```html:preview
<sl-drawer label="Drawer" placement="top" class="drawer-placement-top">
This drawer slides in from the top.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-placement-top');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" placement="top" open={open} onSlAfterHide={() => setOpen(false)}>
This drawer slides in from the top.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
### Slide in From Bottom
To make the drawer slide in from the bottom, set the `placement` attribute to `bottom`.
```html:preview
<sl-drawer label="Drawer" placement="bottom" class="drawer-placement-bottom">
This drawer slides in from the bottom.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-placement-bottom');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" placement="bottom" open={open} onSlAfterHide={() => setOpen(false)}>
This drawer slides in from the bottom.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
### Contained to an Element
By default, drawers slide out of their [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make a drawer slide out of a parent element, add the `contained` attribute to the drawer and apply `position: relative` to its parent.
Unlike normal drawers, contained drawers are not modal. This means they do not show an overlay, they do not trap focus, and they are not dismissible with [[Escape]]. This is intentional to allow users to interact with elements outside of the drawer.
```html:preview
<div
style="position: relative; border: solid 2px var(--sl-panel-border-color); height: 300px; padding: 1rem; margin-bottom: 1rem;"
>
The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer opens.
<sl-drawer label="Drawer" contained class="drawer-contained" style="--size: 50%;">
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
</div>
<sl-button>Toggle Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-contained');
const openButton = drawer.parentElement.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => (drawer.open = !drawer.open));
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<div
style={{
position: 'relative',
border: 'solid 2px var(--sl-panel-border-color)',
height: '300px',
padding: '1rem',
marginBottom: '1rem'
}}
>
The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer
opens.
<SlDrawer
label="Drawer"
contained
no-modal
open={open}
onSlAfterHide={() => setOpen(false)}
style={{ '--size': '50%' }}
>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
</div>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
{% endraw %}
### Custom Size
Use the `--size` custom property to set the drawer's size. This will be applied to the drawer's width or height depending on its `placement`.
```html:preview
<sl-drawer label="Drawer" class="drawer-custom-size" style="--size: 50vw;">
This drawer is always 50% of the viewport.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-custom-size');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)} style={{ '--size': '50vw' }}>
This drawer is always 50% of the viewport.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
{% endraw %}
### Scrolling
By design, a drawer's height will never exceed 100% of its container. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.
```html:preview
<sl-drawer label="Drawer" class="drawer-scrolling">
<div style="height: 150vh; border: dashed 2px var(--sl-color-neutral-200); padding: 0 1rem;">
<p>Scroll down and give it a try! 👇</p>
</div>
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-scrolling');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
<div
style={{
height: '150vh',
border: 'dashed 2px var(--sl-color-neutral-200)',
padding: '0 1rem'
}}
>
<p>Scroll down and give it a try! 👇</p>
</div>
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
{% endraw %}
### Header Actions
The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
```html:preview
<sl-drawer label="Drawer" class="drawer-header-actions">
<sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-header-actions');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
const newWindowButton = drawer.querySelector('.new-window');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
newWindowButton.addEventListener('click', () => window.open(location.href));
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer, SlIconButton } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
<SlIconButton slot="header-actions" name="box-arrow-up-right" onClick={() => window.open(location.href)} />
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
### Preventing the Drawer from Closing
By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the [[Escape]] key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
To keep the drawer open in such cases, you can cancel the `sl-request-close` event. When canceled, the drawer will remain open and pulse briefly to draw the user's attention to it.
You can use `event.detail.source` to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
```html:preview
<sl-drawer label="Drawer" class="drawer-deny-close">
This drawer will not close when you click on the overlay.
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-deny-close');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
// Prevent the drawer from closing when the user clicks on the overlay
drawer.addEventListener('sl-request-close', event => {
if (event.detail.source === 'overlay') {
event.preventDefault();
}
});
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
// Prevent the drawer from closing when the user clicks on the overlay
function handleRequestClose(event) {
if (event.detail.source === 'overlay') {
event.preventDefault();
}
}
return (
<>
<SlDrawer label="Drawer" open={open} onSlRequestClose={handleRequestClose} onSlAfterHide={() => setOpen(false)}>
This drawer will not close when you click on the overlay.
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Save &amp; Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
### Customizing Initial Focus
By default, the drawer's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the drawer. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
```html:preview
<sl-drawer label="Drawer" class="drawer-focus">
<sl-input autofocus placeholder="I will have focus when the drawer is opened"></sl-input>
<sl-button slot="footer" variant="primary">Close</sl-button>
</sl-drawer>
<sl-button>Open Drawer</sl-button>
<script>
const drawer = document.querySelector('.drawer-focus');
const input = drawer.querySelector('sl-input');
const openButton = drawer.nextElementSibling;
const closeButton = drawer.querySelector('sl-button[variant="primary"]');
openButton.addEventListener('click', () => drawer.show());
closeButton.addEventListener('click', () => drawer.hide());
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlDrawer, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
<SlInput autofocus placeholder="I will have focus when the drawer is opened" />
<SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
Close
</SlButton>
</SlDrawer>
<SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
</>
);
};
```
:::tip
You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
:::

365
docs/pages/components/dropdown.md Normal file
View File

@@ -0,0 +1,365 @@
---
meta:
title: Dropdown
description: 'Dropdowns expose additional content that "drops down" in a panel.'
layout: component
---
Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.
Dropdowns are designed to work well with [menus](/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker) and [select](/components/select)). The API gives you complete control over showing, hiding, and positioning the panel.
```html:preview
<sl-dropdown>
<sl-button slot="trigger" caret>Dropdown</sl-button>
<sl-menu>
<sl-menu-item>Dropdown Item 1</sl-menu-item>
<sl-menu-item>Dropdown Item 2</sl-menu-item>
<sl-menu-item>Dropdown Item 3</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item type="checkbox" checked>Checkbox</sl-menu-item>
<sl-menu-item disabled>Disabled</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item>
Prefix
<sl-icon slot="prefix" name="gift"></sl-icon>
</sl-menu-item>
<sl-menu-item>
Suffix Icon
<sl-icon slot="suffix" name="heart"></sl-icon>
</sl-menu-item>
</sl-menu>
</sl-dropdown>
```
```jsx:react
import { SlButton, SlDivider, SlDropdown, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlDropdown>
<SlButton slot="trigger" caret>
Dropdown
</SlButton>
<SlMenu>
<SlMenuItem>Dropdown Item 1</SlMenuItem>
<SlMenuItem>Dropdown Item 2</SlMenuItem>
<SlMenuItem>Dropdown Item 3</SlMenuItem>
<SlDivider />
<SlMenuItem type="checkbox" checked>
Checkbox
</SlMenuItem>
<SlMenuItem disabled>Disabled</SlMenuItem>
<SlDivider />
<SlMenuItem>
Prefix
<SlIcon slot="prefix" name="gift" />
</SlMenuItem>
<SlMenuItem>
Suffix Icon
<SlIcon slot="suffix" name="heart" />
</SlMenuItem>
</SlMenu>
</SlDropdown>
);
```
## Examples
### Getting the Selected Item
When dropdowns are used with [menus](/components/menu), you can listen for the [`sl-select`](/components/menu#events) event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
```html:preview
<div class="dropdown-selection">
<sl-dropdown>
<sl-button slot="trigger" caret>Edit</sl-button>
<sl-menu>
<sl-menu-item value="cut">Cut</sl-menu-item>
<sl-menu-item value="copy">Copy</sl-menu-item>
<sl-menu-item value="paste">Paste</sl-menu-item>
</sl-menu>
</sl-dropdown>
</div>
<script>
const container = document.querySelector('.dropdown-selection');
const dropdown = container.querySelector('sl-dropdown');
dropdown.addEventListener('sl-select', event => {
const selectedItem = event.detail.item;
console.log(selectedItem.value);
});
</script>
```
```jsx:react
import { SlButton, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleSelect(event) {
const selectedItem = event.detail.item;
console.log(selectedItem.value);
}
return (
<SlDropdown>
<SlButton slot="trigger" caret>
Edit
</SlButton>
<SlMenu onSlSelect={handleSelect}>
<SlMenuItem value="cut">Cut</SlMenuItem>
<SlMenuItem value="copy">Copy</SlMenuItem>
<SlMenuItem value="paste">Paste</SlMenuItem>
</SlMenu>
</SlDropdown>
);
};
```
Alternatively, you can listen for the `click` event on individual menu items. Note that, using this approach, disabled menu items will still emit a `click` event.
```html:preview
<div class="dropdown-selection-alt">
<sl-dropdown>
<sl-button slot="trigger" caret>Edit</sl-button>
<sl-menu>
<sl-menu-item value="cut">Cut</sl-menu-item>
<sl-menu-item value="copy">Copy</sl-menu-item>
<sl-menu-item value="paste">Paste</sl-menu-item>
</sl-menu>
</sl-dropdown>
</div>
<script>
const container = document.querySelector('.dropdown-selection-alt');
const cut = container.querySelector('sl-menu-item[value="cut"]');
const copy = container.querySelector('sl-menu-item[value="copy"]');
const paste = container.querySelector('sl-menu-item[value="paste"]');
cut.addEventListener('click', () => console.log('cut'));
copy.addEventListener('click', () => console.log('copy'));
paste.addEventListener('click', () => console.log('paste'));
</script>
```
```jsx:react
import { SlButton, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleCut() {
console.log('cut');
}
function handleCopy() {
console.log('copy');
}
function handlePaste() {
console.log('paste');
}
return (
<SlDropdown>
<SlButton slot="trigger" caret>
Edit
</SlButton>
<SlMenu>
<SlMenuItem onClick={handleCut}>Cut</SlMenuItem>
<SlMenuItem onClick={handleCopy}>Copy</SlMenuItem>
<SlMenuItem onClick={handlePaste}>Paste</SlMenuItem>
</SlMenu>
</SlDropdown>
);
};
```
### Placement
The preferred placement of the dropdown can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport.
```html:preview
<sl-dropdown placement="top-start">
<sl-button slot="trigger" caret>Edit</sl-button>
<sl-menu>
<sl-menu-item>Cut</sl-menu-item>
<sl-menu-item>Copy</sl-menu-item>
<sl-menu-item>Paste</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item>Find</sl-menu-item>
<sl-menu-item>Replace</sl-menu-item>
</sl-menu>
</sl-dropdown>
```
```jsx:react
import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlDropdown placement="top-start">
<SlButton slot="trigger" caret>
Edit
</SlButton>
<SlMenu>
<SlMenuItem>Cut</SlMenuItem>
<SlMenuItem>Copy</SlMenuItem>
<SlMenuItem>Paste</SlMenuItem>
<SlDivider />
<SlMenuItem>Find</SlMenuItem>
<SlMenuItem>Replace</SlMenuItem>
</SlMenu>
</SlDropdown>
);
```
### Distance
The distance from the panel to the trigger can be customized using the `distance` attribute. This value is specified in pixels.
```html:preview
<sl-dropdown distance="30">
<sl-button slot="trigger" caret>Edit</sl-button>
<sl-menu>
<sl-menu-item>Cut</sl-menu-item>
<sl-menu-item>Copy</sl-menu-item>
<sl-menu-item>Paste</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item>Find</sl-menu-item>
<sl-menu-item>Replace</sl-menu-item>
</sl-menu>
</sl-dropdown>
```
```jsx:react
import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlDropdown distance={30}>
<SlButton slot="trigger" caret>
Edit
</SlButton>
<SlMenu>
<SlMenuItem>Cut</SlMenuItem>
<SlMenuItem>Copy</SlMenuItem>
<SlMenuItem>Paste</SlMenuItem>
<SlDivider />
<SlMenuItem>Find</SlMenuItem>
<SlMenuItem>Replace</SlMenuItem>
</SlMenu>
</SlDropdown>
);
```
### Skidding
The offset of the panel along the trigger can be customized using the `skidding` attribute. This value is specified in pixels.
```html:preview
<sl-dropdown skidding="30">
<sl-button slot="trigger" caret>Edit</sl-button>
<sl-menu>
<sl-menu-item>Cut</sl-menu-item>
<sl-menu-item>Copy</sl-menu-item>
<sl-menu-item>Paste</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item>Find</sl-menu-item>
<sl-menu-item>Replace</sl-menu-item>
</sl-menu>
</sl-dropdown>
```
```jsx:react
import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlDropdown skidding={30}>
<SlButton slot="trigger" caret>
Edit
</SlButton>
<SlMenu>
<SlMenuItem>Cut</SlMenuItem>
<SlMenuItem>Copy</SlMenuItem>
<SlMenuItem>Paste</SlMenuItem>
<SlDivider />
<SlMenuItem>Find</SlMenuItem>
<SlMenuItem>Replace</SlMenuItem>
</SlMenu>
</SlDropdown>
);
```
### Hoisting
Dropdown panels will be clipped if they're inside a container that has `overflow: auto|hidden`. The `hoist` attribute forces the panel to use a fixed positioning strategy, allowing it to break out of the container. In this case, the panel will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
```html:preview
<div class="dropdown-hoist">
<sl-dropdown>
<sl-button slot="trigger" caret>No Hoist</sl-button>
<sl-menu>
<sl-menu-item>Item 1</sl-menu-item>
<sl-menu-item>Item 2</sl-menu-item>
<sl-menu-item>Item 3</sl-menu-item>
</sl-menu>
</sl-dropdown>
<sl-dropdown hoist>
<sl-button slot="trigger" caret>Hoist</sl-button>
<sl-menu>
<sl-menu-item>Item 1</sl-menu-item>
<sl-menu-item>Item 2</sl-menu-item>
<sl-menu-item>Item 3</sl-menu-item>
</sl-menu>
</sl-dropdown>
</div>
<style>
.dropdown-hoist {
position: relative;
border: solid 2px var(--sl-panel-border-color);
padding: var(--sl-spacing-medium);
overflow: hidden;
}
</style>
```
```jsx:react
import { SlButton, SlDivider, SlDropdown, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const css = `
.dropdown-hoist {
border: solid 2px var(--sl-panel-border-color);
padding: var(--sl-spacing-medium);
overflow: hidden;
}
`;
const App = () => (
<>
<div className="dropdown-hoist">
<SlDropdown>
<SlButton slot="trigger" caret>
No Hoist
</SlButton>
<SlMenu>
<SlMenuItem>Item 1</SlMenuItem>
<SlMenuItem>Item 2</SlMenuItem>
<SlMenuItem>Item 3</SlMenuItem>
</SlMenu>
</SlDropdown>
<SlDropdown hoist>
<SlButton slot="trigger" caret>
Hoist
</SlButton>
<SlMenu>
<SlMenuItem>Item 1</SlMenuItem>
<SlMenuItem>Item 2</SlMenuItem>
<SlMenuItem>Item 3</SlMenuItem>
</SlMenu>
</SlDropdown>
</div>
<style>{css}</style>
</>
);
```

132
docs/pages/components/format-bytes.md Normal file
View File

@@ -0,0 +1,132 @@
---
meta:
title: Format Bytes
description: Formats a number as a human readable bytes value.
layout: component
---
```html:preview
<div class="format-bytes-overview">
The file is <sl-format-bytes value="1000"></sl-format-bytes> in size. <br /><br />
<sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>
</div>
<script>
const container = document.querySelector('.format-bytes-overview');
const formatter = container.querySelector('sl-format-bytes');
const input = container.querySelector('sl-input');
input.addEventListener('sl-input', () => (formatter.value = input.value || 0));
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlButton, SlFormatBytes, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [value, setValue] = useState(1000);
return (
<>
The file is <SlFormatBytes value={value} /> in size.
<br />
<br />
<SlInput
type="number"
value={value}
label="Number to Format"
style={{ maxWidth: '180px' }}
onSlInput={event => setValue(event.target.value)}
/>
</>
);
};
```
{% endraw %}
## Examples
### Formatting Bytes
Set the `value` attribute to a number to get the value in bytes.
```html:preview
<sl-format-bytes value="12"></sl-format-bytes><br />
<sl-format-bytes value="1200"></sl-format-bytes><br />
<sl-format-bytes value="1200000"></sl-format-bytes><br />
<sl-format-bytes value="1200000000"></sl-format-bytes>
```
```jsx:react
import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlFormatBytes value="12" />
<br />
<SlFormatBytes value="1200" />
<br />
<SlFormatBytes value="1200000" />
<br />
<SlFormatBytes value="1200000000" />
</>
);
```
### Formatting Bits
To get the value in bits, set the `unit` attribute to `bit`.
```html:preview
<sl-format-bytes value="12" unit="bit"></sl-format-bytes><br />
<sl-format-bytes value="1200" unit="bit"></sl-format-bytes><br />
<sl-format-bytes value="1200000" unit="bit"></sl-format-bytes><br />
<sl-format-bytes value="1200000000" unit="bit"></sl-format-bytes>
```
```jsx:react
import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlFormatBytes value="12" unit="bit" />
<br />
<SlFormatBytes value="1200" unit="bit" />
<br />
<SlFormatBytes value="1200000" unit="bit" />
<br />
<SlFormatBytes value="1200000000" unit="bit" />
</>
);
```
### Localization
Use the `lang` attribute to set the number formatting locale.
```html:preview
<sl-format-bytes value="12" lang="de"></sl-format-bytes><br />
<sl-format-bytes value="1200" lang="de"></sl-format-bytes><br />
<sl-format-bytes value="1200000" lang="de"></sl-format-bytes><br />
<sl-format-bytes value="1200000000" lang="de"></sl-format-bytes>
```
```jsx:react
import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlFormatBytes value="12" lang="de" />
<br />
<SlFormatBytes value="1200" lang="de" />
<br />
<SlFormatBytes value="1200000" lang="de" />
<br />
<SlFormatBytes value="1200000000" lang="de" />
</>
);
```

127
docs/pages/components/format-date.md Normal file
View File

@@ -0,0 +1,127 @@
---
meta:
title: Format Date
description: Formats a date/time using the specified locale and options.
layout: component
---
Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). No language packs are required.
```html:preview
<!-- Shoelace 2 release date 🎉 -->
<sl-format-date date="2020-07-15T09:17:00-04:00"></sl-format-date>
```
```jsx:react
import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlFormatDate date="2020-07-15T09:17:00-04:00" />;
```
The `date` attribute determines the date/time to use when formatting. It must be a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object set via JavaScript. If omitted, the current date/time will be assumed.
:::tip
When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
:::
## Examples
### Date & Time Formatting
Formatting options are based on those found in the [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). When formatting options are provided, the date/time will be formatted according to those values. When no formatting options are provided, a localized, numeric date will be displayed instead.
```html:preview
<!-- Human-readable date -->
<sl-format-date month="long" day="numeric" year="numeric"></sl-format-date><br />
<!-- Time -->
<sl-format-date hour="numeric" minute="numeric"></sl-format-date><br />
<!-- Weekday -->
<sl-format-date weekday="long"></sl-format-date><br />
<!-- Month -->
<sl-format-date month="long"></sl-format-date><br />
<!-- Year -->
<sl-format-date year="numeric"></sl-format-date><br />
<!-- No formatting options -->
<sl-format-date></sl-format-date>
```
```jsx:react
import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
{/* Human-readable date */}
<SlFormatDate month="long" day="numeric" year="numeric" />
<br />
{/* Time */}
<SlFormatDate hour="numeric" minute="numeric" />
<br />
{/* Weekday */}
<SlFormatDate weekday="long" />
<br />
{/* Month */}
<SlFormatDate month="long" />
<br />
{/* Year */}
<SlFormatDate year="numeric" />
<br />
{/* No formatting options */}
<SlFormatDate />
</>
);
```
### Hour Formatting
By default, the browser will determine whether to use 12-hour or 24-hour time. To force one or the other, set the `hour-format` attribute to `12` or `24`.
```html:preview
<sl-format-date hour="numeric" minute="numeric" hour-format="12"></sl-format-date><br />
<sl-format-date hour="numeric" minute="numeric" hour-format="24"></sl-format-date>
```
```jsx:react
import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlFormatDate hour="numeric" minute="numeric" hour-format="12" />
<br />
<SlFormatDate hour="numeric" minute="numeric" hour-format="24" />
</>
);
```
### Localization
Use the `lang` attribute to set the date/time formatting locale.
```html:preview
English: <sl-format-date lang="en"></sl-format-date><br />
French: <sl-format-date lang="fr"></sl-format-date><br />
Russian: <sl-format-date lang="ru"></sl-format-date>
```
```jsx:react
import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
English: <SlFormatDate lang="en" />
<br />
French: <SlFormatDate lang="fr" />
<br />
Russian: <SlFormatDate lang="ru" />
</>
);
```

138
docs/pages/components/format-number.md Normal file
View File

@@ -0,0 +1,138 @@
---
meta:
title: Format Number
description: Formats a number using the specified locale and options.
layout: component
---
Localization is handled by the browser's [`Intl.NumberFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). No language packs are required.
```html:preview
<div class="format-number-overview">
<sl-format-number value="1000"></sl-format-number>
<br /><br />
<sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>
</div>
<script>
const container = document.querySelector('.format-number-overview');
const formatter = container.querySelector('sl-format-number');
const input = container.querySelector('sl-input');
input.addEventListener('sl-input', () => (formatter.value = input.value || 0));
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlFormatNumber, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [value, setValue] = useState(1000);
return (
<>
<SlFormatNumber value={value} />
<br />
<br />
<SlInput
type="number"
value={value}
label="Number to Format"
style={{ maxWidth: '180px' }}
onSlInput={event => setValue(event.target.value)}
/>
</>
);
};
```
{% endraw %}
## Examples
### Percentages
To get the value as a percent, set the `type` attribute to `percent`.
```html:preview
<sl-format-number type="percent" value="0"></sl-format-number><br />
<sl-format-number type="percent" value="0.25"></sl-format-number><br />
<sl-format-number type="percent" value="0.50"></sl-format-number><br />
<sl-format-number type="percent" value="0.75"></sl-format-number><br />
<sl-format-number type="percent" value="1"></sl-format-number>
```
```jsx:react
import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlFormatNumber type="percent" value={0} />
<br />
<SlFormatNumber type="percent" value={0.25} />
<br />
<SlFormatNumber type="percent" value={0.5} />
<br />
<SlFormatNumber type="percent" value={0.75} />
<br />
<SlFormatNumber type="percent" value={1} />
</>
);
```
### Localization
Use the `lang` attribute to set the number formatting locale.
```html:preview
English: <sl-format-number value="2000" lang="en" minimum-fraction-digits="2"></sl-format-number><br />
German: <sl-format-number value="2000" lang="de" minimum-fraction-digits="2"></sl-format-number><br />
Russian: <sl-format-number value="2000" lang="ru" minimum-fraction-digits="2"></sl-format-number>
```
```jsx:react
import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
English: <SlFormatNumber value="2000" lang="en" minimum-fraction-digits="2" />
<br />
German: <SlFormatNumber value="2000" lang="de" minimum-fraction-digits="2" />
<br />
Russian: <SlFormatNumber value="2000" lang="ru" minimum-fraction-digits="2" />
</>
);
```
### Currency
To format a number as a monetary value, set the `type` attribute to `currency` and set the `currency` attribute to the desired ISO 4217 currency code. You should also specify `lang` to ensure the the number is formatted correctly for the target locale.
```html:preview
<sl-format-number type="currency" currency="USD" value="2000" lang="en-US"></sl-format-number><br />
<sl-format-number type="currency" currency="GBP" value="2000" lang="en-GB"></sl-format-number><br />
<sl-format-number type="currency" currency="EUR" value="2000" lang="de"></sl-format-number><br />
<sl-format-number type="currency" currency="RUB" value="2000" lang="ru"></sl-format-number><br />
<sl-format-number type="currency" currency="CNY" value="2000" lang="zh-cn"></sl-format-number>
```
```jsx:react
import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlFormatNumber type="currency" currency="USD" value="2000" lang="en-US" />
<br />
<SlFormatNumber type="currency" currency="GBP" value="2000" lang="en-GB" />
<br />
<SlFormatNumber type="currency" currency="EUR" value="2000" lang="de" />
<br />
<SlFormatNumber type="currency" currency="RUB" value="2000" lang="ru" />
<br />
<SlFormatNumber type="currency" currency="CNY" value="2000" lang="zh-cn" />
</>
);
```

152
docs/pages/components/icon-button.md Normal file
View File

@@ -0,0 +1,152 @@
---
meta:
title: Icon Button
description: Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
layout: component
---
For a full list of icons that come bundled with Shoelace, refer to the [icon component](/components/icon).
```html:preview
<sl-icon-button name="gear" label="Settings"></sl-icon-button>
```
```jsx:react
import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlIconButton name="gear" label="Settings" />;
```
## Examples
### Sizes
Icon buttons inherit their parent element's `font-size`.
```html:preview
<sl-icon-button name="pencil" label="Edit" style="font-size: 1.5rem;"></sl-icon-button>
<sl-icon-button name="pencil" label="Edit" style="font-size: 2rem;"></sl-icon-button>
<sl-icon-button name="pencil" label="Edit" style="font-size: 2.5rem;"></sl-icon-button>
```
{% raw %}
```jsx:react
import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlIconButton name="pencil" label="Edit" style={{ fontSize: '1.5rem' }} />
<SlIconButton name="pencil" label="Edit" style={{ fontSize: '2rem' }} />
<SlIconButton name="pencil" label="Edit" style={{ fontSize: '2.5rem' }} />
</>
);
```
{% endraw %}
### Colors
Icon buttons are designed to have a uniform appearance, so their color is not inherited. However, you can still customize them by styling the `base` part.
```html:preview
<div class="icon-button-color">
<sl-icon-button name="type-bold" label="Bold"></sl-icon-button>
<sl-icon-button name="type-italic" label="Italic"></sl-icon-button>
<sl-icon-button name="type-underline" label="Underline"></sl-icon-button>
</div>
<style>
.icon-button-color sl-icon-button::part(base) {
color: #b00091;
}
.icon-button-color sl-icon-button::part(base):hover,
.icon-button-color sl-icon-button::part(base):focus {
color: #c913aa;
}
.icon-button-color sl-icon-button::part(base):active {
color: #960077;
}
</style>
```
```jsx:react
import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
const css = `
.icon-button-color sl-icon-button::part(base) {
color: #b00091;
}
.icon-button-color sl-icon-button::part(base):hover,
.icon-button-color sl-icon-button::part(base):focus {
color: #c913aa;
}
.icon-button-color sl-icon-button::part(base):active {
color: #960077;
}
`;
const App = () => (
<>
<div className="icon-button-color">
<SlIconButton name="type-bold" label="Bold" />
<SlIconButton name="type-italic" label="Italic" />
<SlIconButton name="type-underline" label="Underline" />
</div>
<style>{css}</style>
</>
);
```
### Link Buttons
Use the `href` attribute to convert the button to a link.
```html:preview
<sl-icon-button name="gear" label="Settings" href="https://example.com" target="_blank"></sl-icon-button>
```
```jsx:react
import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlIconButton name="gear" label="Settings" href="https://example.com" target="_blank" />;
```
### Icon Button with Tooltip
Wrap a tooltip around an icon button to provide contextual information to the user.
```html:preview
<sl-tooltip content="Settings">
<sl-icon-button name="gear" label="Settings"></sl-icon-button>
</sl-tooltip>
```
```jsx:react
import { SlIconButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTooltip content="Settings">
<SlIconButton name="gear" label="Settings" />
</SlTooltip>
);
```
### Disabled
Use the `disabled` attribute to disable the icon button.
```html:preview
<sl-icon-button name="gear" label="Settings" disabled></sl-icon-button>
```
```jsx:react
import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlIconButton name="gear" label="Settings" disabled />;
```

838
docs/pages/components/icon.md Normal file
View File

@@ -0,0 +1,838 @@
---
meta:
title: Icon
description: Icons are symbols that can be used to represent various options within an application.
layout: component
---
Shoelace comes bundled with over 1,500 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. These icons are part of the `default` icon library. If you prefer, you can register [custom icon libraries](#icon-libraries) as well.
:::tip
Depending on how you're loading Shoelace, you may need to copy icon assets and/or [set the base path](getting-started/installation#setting-the-base-path) so Shoelace knows where to load them from. Otherwise, icons may not appear and you'll see 404 Not Found errors in the dev console.
:::
## Default Icons
All available icons in the `default` icon library are shown below. Click or tap on any icon to copy its name, then you can use it in your HTML like this.
```html
<sl-icon name="icon-name-here"></sl-icon>
```
<div class="icon-search">
<div class="icon-search-controls">
<sl-input placeholder="Search Icons" clearable>
<sl-icon slot="prefix" name="search"></sl-icon>
</sl-input>
<sl-select value="outline">
<sl-option value="outline">Outlined</sl-option>
<sl-option value="fill">Filled</sl-option>
<sl-option value="all">All icons</sl-option>
</sl-select>
</div>
<div class="icon-list"></div>
<input type="text" class="icon-copy-input" aria-hidden="true" tabindex="-1">
</div>
## Examples
### Colors
Icons inherit their color from the current text color. Thus, you can set the `color` property on the `<sl-icon>` element or an ancestor to change the color.
```html:preview
<div style="color: #4a90e2;">
<sl-icon name="exclamation-triangle"></sl-icon>
<sl-icon name="archive"></sl-icon>
<sl-icon name="battery-charging"></sl-icon>
<sl-icon name="bell"></sl-icon>
</div>
<div style="color: #9013fe;">
<sl-icon name="clock"></sl-icon>
<sl-icon name="cloud"></sl-icon>
<sl-icon name="download"></sl-icon>
<sl-icon name="file-earmark"></sl-icon>
</div>
<div style="color: #417505;">
<sl-icon name="flag"></sl-icon>
<sl-icon name="heart"></sl-icon>
<sl-icon name="image"></sl-icon>
<sl-icon name="lightning"></sl-icon>
</div>
<div style="color: #f5a623;">
<sl-icon name="mic"></sl-icon>
<sl-icon name="search"></sl-icon>
<sl-icon name="star"></sl-icon>
<sl-icon name="trash"></sl-icon>
</div>
```
{% raw %}
```jsx:react
import { SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<div style={{ color: '#4a90e2' }}>
<SlIcon name="exclamation-triangle"></SlIcon>
<SlIcon name="archive"></SlIcon>
<SlIcon name="battery-charging"></SlIcon>
<SlIcon name="bell"></SlIcon>
</div>
<div style={{ color: '#9013fe' }}>
<SlIcon name="clock"></SlIcon>
<SlIcon name="cloud"></SlIcon>
<SlIcon name="download"></SlIcon>
<SlIcon name="file-earmark"></SlIcon>
</div>
<div style={{ color: '#417505' }}>
<SlIcon name="flag"></SlIcon>
<SlIcon name="heart"></SlIcon>
<SlIcon name="image"></SlIcon>
<SlIcon name="lightning"></SlIcon>
</div>
<div style={{ color: '#f5a623' }}>
<SlIcon name="mic"></SlIcon>
<SlIcon name="search"></SlIcon>
<SlIcon name="star"></SlIcon>
<SlIcon name="trash"></SlIcon>
</div>
</>
);
```
{% endraw %}
### Sizing
Icons are sized relative to the current font size. To change their size, set the `font-size` property on the icon itself or on a parent element as shown below.
```html:preview
<div style="font-size: 32px;">
<sl-icon name="exclamation-triangle"></sl-icon>
<sl-icon name="archive"></sl-icon>
<sl-icon name="battery-charging"></sl-icon>
<sl-icon name="bell"></sl-icon>
<sl-icon name="clock"></sl-icon>
<sl-icon name="cloud"></sl-icon>
<sl-icon name="download"></sl-icon>
<sl-icon name="file-earmark"></sl-icon>
<sl-icon name="flag"></sl-icon>
<sl-icon name="heart"></sl-icon>
<sl-icon name="image"></sl-icon>
<sl-icon name="lightning"></sl-icon>
<sl-icon name="mic"></sl-icon>
<sl-icon name="search"></sl-icon>
<sl-icon name="star"></sl-icon>
<sl-icon name="trash"></sl-icon>
</div>
```
{% raw %}
```jsx:react
import { SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<div style={{ fontSize: '32px' }}>
<SlIcon name="exclamation-triangle" />
<SlIcon name="archive" />
<SlIcon name="battery-charging" />
<SlIcon name="bell" />
<SlIcon name="clock" />
<SlIcon name="cloud" />
<SlIcon name="download" />
<SlIcon name="file-earmark" />
<SlIcon name="flag" />
<SlIcon name="heart" />
<SlIcon name="image" />
<SlIcon name="lightning" />
<SlIcon name="mic" />
<SlIcon name="search" />
<SlIcon name="star" />
<SlIcon name="trash" />
</div>
);
```
{% endraw %}
### Labels
For non-decorative icons, use the `label` attribute to announce it to assistive devices.
```html:preview
<sl-icon name="star-fill" label="Add to favorites"></sl-icon>
```
```jsx:react
import { SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlIcon name="star-fill" label="Add to favorites" />;
```
### Custom Icons
Custom icons can be loaded individually with the `src` attribute. Only SVGs on a local or CORS-enabled endpoint are supported. If you're using more than one custom icon, it might make sense to register a [custom icon library](#icon-libraries).
```html:preview
<sl-icon src="https://shoelace.style/assets/images/shoe.svg" style="font-size: 8rem;"></sl-icon>
```
{% raw %}
```jsx:react
import { SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlIcon src="https://shoelace.style/assets/images/shoe.svg" style={{ fontSize: '8rem' }}></SlIcon>;
```
{% endraw %}
## Icon Libraries
You can register additional icons to use with the `<sl-icon>` component through icon libraries. Icon files can exist locally or on a CORS-enabled endpoint (e.g. a CDN). There is no limit to how many icon libraries you can register and there is no cost associated with registering them, as individual icons are only requested when they're used.
Shoelace ships with two built-in icon libraries, `default` and `system`. The [default icon library](#customizing-the-default-library) contains all of the icons in the Bootstrap Icons project. The [system icon library](#customizing-the-system-library) contains only a small subset of icons that are used internally by Shoelace components.
To register an additional icon library, use the `registerIconLibrary()` function that's exported from `utilities/icon-library.js`. At a minimum, you must provide a name and a resolver function. The resolver function translates an icon name to a URL where the corresponding SVG file exists. Refer to the examples below to better understand how it works.
If necessary, a mutator function can be used to mutate the SVG element before rendering. This is necessary for some libraries due to the many possible ways SVGs are crafted. For example, icons should ideally inherit the current text color via `currentColor`, so you may need to apply `fill="currentColor` or `stroke="currentColor"` to the SVG element using this function.
Here's an example that registers an icon library located in the `/assets/icons` directory.
```html
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('my-icons', {
resolver: name => `/assets/icons/${name}.svg`,
mutator: svg => svg.setAttribute('fill', 'currentColor')
});
</script>
```
To display an icon, set the `library` and `name` attributes of an `<sl-icon>` element.
```html
<!-- This will show the icon located at /assets/icons/smile.svg -->
<sl-icon library="my-icons" name="smile"></sl-icon>
```
If an icon is used before registration occurs, it will be empty initially but shown when registered.
The following examples demonstrate how to register a number of popular, open source icon libraries via CDN. Feel free to adapt the code as you see fit to use your own origin or naming conventions.
### Boxicons
This will register the [Boxicons](https://boxicons.com/) library using the jsDelivr CDN. This library has three variations: regular (`bx-*`), solid (`bxs-*`), and logos (`bxl-*`). A mutator function is required to set the SVG's `fill` to `currentColor`.
Icons in this library are licensed under the [Creative Commons 4.0 License](https://github.com/atisawd/boxicons#license).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('boxicons', {
resolver: name => {
let folder = 'regular';
if (name.substring(0, 4) === 'bxs-') folder = 'solid';
if (name.substring(0, 4) === 'bxl-') folder = 'logos';
return `https://cdn.jsdelivr.net/npm/boxicons@2.0.5/svg/${folder}/${name}.svg`;
},
mutator: svg => svg.setAttribute('fill', 'currentColor')
});
</script>
<div style="font-size: 24px;">
<sl-icon library="boxicons" name="bx-bot"></sl-icon>
<sl-icon library="boxicons" name="bx-cookie"></sl-icon>
<sl-icon library="boxicons" name="bx-joystick"></sl-icon>
<sl-icon library="boxicons" name="bx-save"></sl-icon>
<sl-icon library="boxicons" name="bx-server"></sl-icon>
<sl-icon library="boxicons" name="bx-wine"></sl-icon>
<br />
<sl-icon library="boxicons" name="bxs-bot"></sl-icon>
<sl-icon library="boxicons" name="bxs-cookie"></sl-icon>
<sl-icon library="boxicons" name="bxs-joystick"></sl-icon>
<sl-icon library="boxicons" name="bxs-save"></sl-icon>
<sl-icon library="boxicons" name="bxs-server"></sl-icon>
<sl-icon library="boxicons" name="bxs-wine"></sl-icon>
<br />
<sl-icon library="boxicons" name="bxl-apple"></sl-icon>
<sl-icon library="boxicons" name="bxl-chrome"></sl-icon>
<sl-icon library="boxicons" name="bxl-edge"></sl-icon>
<sl-icon library="boxicons" name="bxl-firefox"></sl-icon>
<sl-icon library="boxicons" name="bxl-opera"></sl-icon>
<sl-icon library="boxicons" name="bxl-microsoft"></sl-icon>
</div>
```
### Lucide
This will register the [Lucide](https://lucide.dev/) icon library using the jsDelivr CDN. This project is a community-maintained fork of the popular [Feather](https://feathericons.com/) icon library.
Icons in this library are licensed under the [MIT License](https://github.com/lucide-icons/lucide/blob/master/LICENSE).
```html:preview
<div style="font-size: 24px;">
<sl-icon library="lucide" name="feather"></sl-icon>
<sl-icon library="lucide" name="pie-chart"></sl-icon>
<sl-icon library="lucide" name="settings"></sl-icon>
<sl-icon library="lucide" name="map-pin"></sl-icon>
<sl-icon library="lucide" name="printer"></sl-icon>
<sl-icon library="lucide" name="shopping-cart"></sl-icon>
</div>
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('lucide', {
resolver: name => `https://cdn.jsdelivr.net/npm/lucide-static@0.16.29/icons/${name}.svg`
});
</script>
```
### Font Awesome
This will register the [Font Awesome Free](https://fontawesome.com/) library using the jsDelivr CDN. This library has three variations: regular (`far-*`), solid (`fas-*`), and brands (`fab-*`). A mutator function is required to set the SVG's `fill` to `currentColor`.
Icons in this library are licensed under the [Font Awesome Free License](https://github.com/FortAwesome/Font-Awesome/blob/master/LICENSE.txt). Some of the icons that appear on the Font Awesome website require a license and are therefore not available in the CDN.
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('fa', {
resolver: name => {
const filename = name.replace(/^fa[rbs]-/, '');
let folder = 'regular';
if (name.substring(0, 4) === 'fas-') folder = 'solid';
if (name.substring(0, 4) === 'fab-') folder = 'brands';
return `https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5.15.1/svgs/${folder}/${filename}.svg`;
},
mutator: svg => svg.setAttribute('fill', 'currentColor')
});
</script>
<div style="font-size: 24px;">
<sl-icon library="fa" name="far-bell"></sl-icon>
<sl-icon library="fa" name="far-comment"></sl-icon>
<sl-icon library="fa" name="far-hand-point-right"></sl-icon>
<sl-icon library="fa" name="far-hdd"></sl-icon>
<sl-icon library="fa" name="far-heart"></sl-icon>
<sl-icon library="fa" name="far-star"></sl-icon>
<br />
<sl-icon library="fa" name="fas-archive"></sl-icon>
<sl-icon library="fa" name="fas-book"></sl-icon>
<sl-icon library="fa" name="fas-chess-knight"></sl-icon>
<sl-icon library="fa" name="fas-dice"></sl-icon>
<sl-icon library="fa" name="fas-pizza-slice"></sl-icon>
<sl-icon library="fa" name="fas-scroll"></sl-icon>
<br />
<sl-icon library="fa" name="fab-apple"></sl-icon>
<sl-icon library="fa" name="fab-chrome"></sl-icon>
<sl-icon library="fa" name="fab-edge"></sl-icon>
<sl-icon library="fa" name="fab-firefox"></sl-icon>
<sl-icon library="fa" name="fab-opera"></sl-icon>
<sl-icon library="fa" name="fab-microsoft"></sl-icon>
</div>
```
### Heroicons
This will register the [Heroicons](https://heroicons.com/) library using the jsDelivr CDN.
Icons in this library are licensed under the [MIT License](https://github.com/tailwindlabs/heroicons/blob/master/LICENSE).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('heroicons', {
resolver: name => `https://cdn.jsdelivr.net/npm/heroicons@2.0.1/24/outline/${name}.svg`
});
</script>
<div style="font-size: 24px;">
<sl-icon library="heroicons" name="chat-bubble-left"></sl-icon>
<sl-icon library="heroicons" name="cloud"></sl-icon>
<sl-icon library="heroicons" name="cog"></sl-icon>
<sl-icon library="heroicons" name="document-text"></sl-icon>
<sl-icon library="heroicons" name="gift"></sl-icon>
<sl-icon library="heroicons" name="speaker-wave"></sl-icon>
</div>
```
### Iconoir
This will register the [Iconoir](https://iconoir.com/) library using the jsDelivr CDN.
Icons in this library are licensed under the [MIT License](https://github.com/lucaburgio/iconoir/blob/master/LICENSE).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('iconoir', {
resolver: name => `https://cdn.jsdelivr.net/gh/lucaburgio/iconoir@latest/icons/${name}.svg`
});
</script>
<div style="font-size: 24px;">
<sl-icon library="iconoir" name="check-circled-outline"></sl-icon>
<sl-icon library="iconoir" name="drawer"></sl-icon>
<sl-icon library="iconoir" name="keyframes"></sl-icon>
<sl-icon library="iconoir" name="headset-help"></sl-icon>
<sl-icon library="iconoir" name="color-picker"></sl-icon>
<sl-icon library="iconoir" name="wifi"></sl-icon>
</div>
```
### Ionicons
This will register the [Ionicons](https://ionicons.com/) library using the jsDelivr CDN. This library has three variations: outline (default), filled (`*-filled`), and sharp (`*-sharp`). A mutator function is required to polyfill a handful of styles we're not including.
Icons in this library are licensed under the [MIT License](https://github.com/ionic-team/ionicons/blob/master/LICENSE).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('ionicons', {
resolver: name => `https://cdn.jsdelivr.net/npm/ionicons@5.1.2/dist/ionicons/svg/${name}.svg`,
mutator: svg => {
svg.setAttribute('fill', 'currentColor');
svg.setAttribute('stroke', 'currentColor');
[...svg.querySelectorAll('.ionicon-fill-none')].map(el => el.setAttribute('fill', 'none'));
[...svg.querySelectorAll('.ionicon-stroke-width')].map(el => el.setAttribute('stroke-width', '32px'));
}
});
</script>
<div style="font-size: 24px;">
<sl-icon library="ionicons" name="alarm"></sl-icon>
<sl-icon library="ionicons" name="american-football"></sl-icon>
<sl-icon library="ionicons" name="bug"></sl-icon>
<sl-icon library="ionicons" name="chatbubble"></sl-icon>
<sl-icon library="ionicons" name="settings"></sl-icon>
<sl-icon library="ionicons" name="warning"></sl-icon>
<br />
<sl-icon library="ionicons" name="alarm-outline"></sl-icon>
<sl-icon library="ionicons" name="american-football-outline"></sl-icon>
<sl-icon library="ionicons" name="bug-outline"></sl-icon>
<sl-icon library="ionicons" name="chatbubble-outline"></sl-icon>
<sl-icon library="ionicons" name="settings-outline"></sl-icon>
<sl-icon library="ionicons" name="warning-outline"></sl-icon>
<br />
<sl-icon library="ionicons" name="alarm-sharp"></sl-icon>
<sl-icon library="ionicons" name="american-football-sharp"></sl-icon>
<sl-icon library="ionicons" name="bug-sharp"></sl-icon>
<sl-icon library="ionicons" name="chatbubble-sharp"></sl-icon>
<sl-icon library="ionicons" name="settings-sharp"></sl-icon>
<sl-icon library="ionicons" name="warning-sharp"></sl-icon>
</div>
```
### Jam Icons
This will register the [Jam Icons](https://jam-icons.com/) library using the jsDelivr CDN. This library has two variations: regular (default) and filled (`*-f`). A mutator function is required to set the SVG's `fill` to `currentColor`.
Icons in this library are licensed under the [MIT License](https://github.com/michaelampr/jam/blob/master/LICENSE).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('jam', {
resolver: name => `https://cdn.jsdelivr.net/npm/jam-icons@2.0.0/svg/${name}.svg`,
mutator: svg => svg.setAttribute('fill', 'currentColor')
});
</script>
<div style="font-size: 24px;">
<sl-icon library="jam" name="calendar"></sl-icon>
<sl-icon library="jam" name="camera"></sl-icon>
<sl-icon library="jam" name="filter"></sl-icon>
<sl-icon library="jam" name="leaf"></sl-icon>
<sl-icon library="jam" name="picture"></sl-icon>
<sl-icon library="jam" name="set-square"></sl-icon>
<br />
<sl-icon library="jam" name="calendar-f"></sl-icon>
<sl-icon library="jam" name="camera-f"></sl-icon>
<sl-icon library="jam" name="filter-f"></sl-icon>
<sl-icon library="jam" name="leaf-f"></sl-icon>
<sl-icon library="jam" name="picture-f"></sl-icon>
<sl-icon library="jam" name="set-square-f"></sl-icon>
</div>
```
### Material Icons
This will register the [Material Icons](https://material.io/resources/icons/?style=baseline) library using the jsDelivr CDN. This library has three variations: outline (default), round (`*_round`), and sharp (`*_sharp`). A mutator function is required to set the SVG's `fill` to `currentColor`.
Icons in this library are licensed under the [Apache 2.0 License](https://github.com/google/material-design-icons/blob/master/LICENSE).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('material', {
resolver: name => {
const match = name.match(/^(.*?)(_(round|sharp))?$/);
return `https://cdn.jsdelivr.net/npm/@material-icons/svg@1.0.5/svg/${match[1]}/${match[3] || 'outline'}.svg`;
},
mutator: svg => svg.setAttribute('fill', 'currentColor')
});
</script>
<div style="font-size: 24px;">
<sl-icon library="material" name="notifications"></sl-icon>
<sl-icon library="material" name="email"></sl-icon>
<sl-icon library="material" name="delete"></sl-icon>
<sl-icon library="material" name="volume_up"></sl-icon>
<sl-icon library="material" name="settings"></sl-icon>
<sl-icon library="material" name="shopping_basket"></sl-icon>
<br />
<sl-icon library="material" name="notifications_round"></sl-icon>
<sl-icon library="material" name="email_round"></sl-icon>
<sl-icon library="material" name="delete_round"></sl-icon>
<sl-icon library="material" name="volume_up_round"></sl-icon>
<sl-icon library="material" name="settings_round"></sl-icon>
<sl-icon library="material" name="shopping_basket_round"></sl-icon>
<br />
<sl-icon library="material" name="notifications_sharp"></sl-icon>
<sl-icon library="material" name="email_sharp"></sl-icon>
<sl-icon library="material" name="delete_sharp"></sl-icon>
<sl-icon library="material" name="volume_up_sharp"></sl-icon>
<sl-icon library="material" name="settings_sharp"></sl-icon>
<sl-icon library="material" name="shopping_basket_sharp"></sl-icon>
</div>
```
### Remix Icon
This will register the [Remix Icon](https://remixicon.com/) library using the jsDelivr CDN. This library groups icons by categories, so the name must include the category and icon separated by a slash, as well as the `-line` or `-fill` suffix as needed. A mutator function is required to set the SVG's `fill` to `currentColor`.
Icons in this library are licensed under the [Apache 2.0 License](https://github.com/Remix-Design/RemixIcon/blob/master/License).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('remixicon', {
resolver: name => {
const match = name.match(/^(.*?)\/(.*?)?$/);
match[1] = match[1].charAt(0).toUpperCase() + match[1].slice(1);
return `https://cdn.jsdelivr.net/npm/remixicon@2.5.0/icons/${match[1]}/${match[2]}.svg`;
},
mutator: svg => svg.setAttribute('fill', 'currentColor')
});
</script>
<div style="font-size: 24px;">
<sl-icon library="remixicon" name="business/cloud-line"></sl-icon>
<sl-icon library="remixicon" name="design/brush-line"></sl-icon>
<sl-icon library="remixicon" name="business/pie-chart-line"></sl-icon>
<sl-icon library="remixicon" name="development/bug-line"></sl-icon>
<sl-icon library="remixicon" name="media/image-line"></sl-icon>
<sl-icon library="remixicon" name="system/alert-line"></sl-icon>
<br />
<sl-icon library="remixicon" name="business/cloud-fill"></sl-icon>
<sl-icon library="remixicon" name="design/brush-fill"></sl-icon>
<sl-icon library="remixicon" name="business/pie-chart-fill"></sl-icon>
<sl-icon library="remixicon" name="development/bug-fill"></sl-icon>
<sl-icon library="remixicon" name="media/image-fill"></sl-icon>
<sl-icon library="remixicon" name="system/alert-fill"></sl-icon>
</div>
```
### Tabler Icons
This will register the [Tabler Icons](https://tabler-icons.io/) library using the jsDelivr CDN. This library features over 1,950 open source icons.
Icons in this library are licensed under the [MIT License](https://github.com/tabler/tabler-icons/blob/master/LICENSE).
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('tabler', {
resolver: name => `https://cdn.jsdelivr.net/npm/@tabler/icons@1.68.0/icons/${name}.svg`
});
</script>
<div style="font-size: 24px;">
<sl-icon library="tabler" name="alert-triangle"></sl-icon>
<sl-icon library="tabler" name="arrow-back"></sl-icon>
<sl-icon library="tabler" name="at"></sl-icon>
<sl-icon library="tabler" name="ball-baseball"></sl-icon>
<sl-icon library="tabler" name="cake"></sl-icon>
<sl-icon library="tabler" name="files"></sl-icon>
<br />
<sl-icon library="tabler" name="keyboard"></sl-icon>
<sl-icon library="tabler" name="moon"></sl-icon>
<sl-icon library="tabler" name="pig"></sl-icon>
<sl-icon library="tabler" name="printer"></sl-icon>
<sl-icon library="tabler" name="ship"></sl-icon>
<sl-icon library="tabler" name="toilet-paper"></sl-icon>
</div>
```
### Unicons
This will register the [Unicons](https://iconscout.com/unicons) library using the jsDelivr CDN. This library has two variations: line (default) and solid (`*-s`). A mutator function is required to set the SVG's `fill` to `currentColor`.
Icons in this library are licensed under the [Apache 2.0 License](https://github.com/Iconscout/unicons/blob/master/LICENSE). Some of the icons that appear on the Unicons website, particularly many of the solid variations, require a license and are therefore not available in the CDN.
```html:preview
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('unicons', {
resolver: name => {
const match = name.match(/^(.*?)(-s)?$/);
return `https://cdn.jsdelivr.net/npm/@iconscout/unicons@3.0.3/svg/${match[2] === '-s' ? 'solid' : 'line'}/${
match[1]
}.svg`;
},
mutator: svg => svg.setAttribute('fill', 'currentColor')
});
</script>
<div style="font-size: 24px;">
<sl-icon library="unicons" name="clock"></sl-icon>
<sl-icon library="unicons" name="graph-bar"></sl-icon>
<sl-icon library="unicons" name="padlock"></sl-icon>
<sl-icon library="unicons" name="polygon"></sl-icon>
<sl-icon library="unicons" name="rocket"></sl-icon>
<sl-icon library="unicons" name="star"></sl-icon>
<br />
<sl-icon library="unicons" name="clock-s"></sl-icon>
<sl-icon library="unicons" name="graph-bar-s"></sl-icon>
<sl-icon library="unicons" name="padlock-s"></sl-icon>
<sl-icon library="unicons" name="polygon-s"></sl-icon>
<sl-icon library="unicons" name="rocket-s"></sl-icon>
<sl-icon library="unicons" name="star-s"></sl-icon>
</div>
```
### Customizing the Default Library
The default icon library contains over 1,300 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. These are the icons that display when you use `<sl-icon>` without the `library` attribute. If you prefer to have these icons resolve elsewhere or to a different icon library, register an icon library using the `default` name and a custom resolver.
This example will load the same set of icons from the jsDelivr CDN instead of your local assets folder.
```html
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('default', {
resolver: name => `https://cdn.jsdelivr.net/npm/bootstrap-icons@1.0.0/icons/${name}.svg`
});
</script>
```
### Customizing the System Library
The system library contains only the icons used internally by Shoelace components. Unlike the default icon library, the system library does not rely on physical assets. Instead, its icons are hard-coded as data URIs into the resolver to ensure their availability.
If you want to change the icons Shoelace uses internally, you can register an icon library using the `system` name and a custom resolver. If you choose to do this, it's your responsibility to provide all of the icons that are required by components. You can reference `src/components/library.system.ts` for a complete list of system icons used by Shoelace.
```html
<script type="module">
import { registerIconLibrary } from '/dist/utilities/icon-library.js';
registerIconLibrary('system', {
resolver: name => `/path/to/custom/icons/${name}.svg`
});
</script>
```
<!-- Supporting scripts and styles for the search utility -->
<script>
function wrapWithTooltip(item) {
const tooltip = document.createElement('sl-tooltip');
tooltip.content = item.getAttribute('data-name');
// Close open tooltips
document.querySelectorAll('.icon-list sl-tooltip[open]').forEach(tooltip => tooltip.hide());
// Wrap it with a tooltip and trick it into showing up
item.parentNode.insertBefore(tooltip, item);
tooltip.appendChild(item);
requestAnimationFrame(() => tooltip.dispatchEvent(new MouseEvent('mouseover')));
}
fetch('/dist/assets/icons/icons.json')
.then(res => res.json())
.then(icons => {
const container = document.querySelector('.icon-search');
const input = container.querySelector('sl-input');
const select = container.querySelector('sl-select');
const copyInput = container.querySelector('.icon-copy-input');
const loader = container.querySelector('.icon-loader');
const list = container.querySelector('.icon-list');
const queue = [];
let inputTimeout;
// Generate icons
icons.map(i => {
const item = document.createElement('div');
item.classList.add('icon-list-item');
item.setAttribute('data-name', i.name);
item.setAttribute('data-terms', [i.name, i.title, ...(i.tags || []), ...(i.categories || [])].join(' '));
item.innerHTML = `
<svg width="1em" height="1em" fill="currentColor">
<use xlink:href="/assets/icons/sprite.svg#${i.name}"></use>
</svg>
`;
list.appendChild(item);
// Wrap it with a tooltip the first time the mouse lands on it. We do this instead of baking them into the DOM
// to improve this page's performance. See: https://github.com/shoelace-style/shoelace/issues/1122
item.addEventListener('mouseover', () => wrapWithTooltip(item), { once: true });
// Copy on click
item.addEventListener('click', () => {
const tooltip = item.closest('sl-tooltip');
copyInput.value = i.name;
copyInput.select();
document.execCommand('copy');
if (tooltip) {
tooltip.content = 'Copied!';
setTimeout(() => tooltip.content = i.name, 1000);
}
});
});
// Filter as the user types
input.addEventListener('sl-input', () => {
clearTimeout(inputTimeout);
inputTimeout = setTimeout(() => {
[...list.querySelectorAll('.icon-list-item')].map(item => {
const filter = input.value.toLowerCase();
if (filter === '') {
item.hidden = false;
} else {
const terms = item.getAttribute('data-terms').toLowerCase();
item.hidden = terms.indexOf(filter) < 0;
}
});
}, 250);
});
// Sort by type and remember preference
const iconType = sessionStorage.getItem('sl-icon:type') || 'outline';
select.value = iconType;
list.setAttribute('data-type', select.value);
select.addEventListener('sl-change', () => {
list.setAttribute('data-type', select.value);
sessionStorage.setItem('sl-icon:type', select.value);
});
});
</script>
<style>
.icon-search {
border: solid 1px var(--sl-panel-border-color);
border-radius: var(--sl-border-radius-medium);
padding: var(--sl-spacing-medium);
}
.icon-search [hidden] {
display: none;
}
.icon-search-controls {
display: flex;
}
.icon-search-controls sl-input {
flex: 1 1 auto;
}
.icon-search-controls sl-select {
width: 10rem;
flex: 0 0 auto;
margin-left: 1rem;
}
.icon-loader {
display: flex;
align-items: center;
justify-content: center;
min-height: 30vh;
}
.icon-list {
display: grid;
grid-template-columns: repeat(12, 1fr);
position: relative;
margin-top: 1rem;
}
.icon-loader[hidden],
.icon-list[hidden] {
display: none;
}
.icon-list-item {
display: inline-flex;
align-items: center;
justify-content: center;
border-radius: var(--sl-border-radius-medium);
font-size: 24px;
width: 2em;
height: 2em;
margin: 0 auto;
cursor: copy;
transition: var(--sl-transition-medium) all;
}
.icon-list-item:hover {
background-color: var(--sl-color-primary-50);
color: var(--sl-color-primary-600);
}
.icon-list[data-type="outline"] .icon-list-item[data-name$="-fill"] {
display: none;
}
.icon-list[data-type="fill"] .icon-list-item:not([data-name$="-fill"]) {
display: none;
}
.icon-copy-input {
position: absolute;
opacity: 0;
pointer-events: none;
}
@media screen and (max-width: 1000px) {
.icon-list {
grid-template-columns: repeat(8, 1fr);
}
.icon-list-item {
font-size: 20px;
}
.icon-search-controls {
display: block;
}
.icon-search-controls sl-select {
width: auto;
margin: 1rem 0 0 0;
}
}
@media screen and (max-width: 500px) {
.icon-list {
grid-template-columns: repeat(4, 1fr);
}
}
</style>

82
docs/pages/components/image-comparer.md Normal file
View File

@@ -0,0 +1,82 @@
---
meta:
title: Image Comparer
description: Compare visual differences between similar photos with a sliding panel.
layout: component
---
For best results, use images that share the same dimensions. The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.)
```html:preview
<sl-image-comparer>
<img
slot="before"
src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80&sat=-100&bri=-5"
alt="Grayscale version of kittens in a basket looking around."
/>
<img
slot="after"
src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80"
alt="Color version of kittens in a basket looking around."
/>
</sl-image-comparer>
```
```jsx:react
import { SlImageComparer } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlImageComparer>
<img
slot="before"
src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80&sat=-100&bri=-5"
alt="Grayscale version of kittens in a basket looking around."
/>
<img
slot="after"
src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80"
alt="Color version of kittens in a basket looking around."
/>
</SlImageComparer>
);
```
## Examples
### Initial Position
Use the `position` attribute to set the initial position of the slider. This is a percentage from `0` to `100`.
```html:preview
<sl-image-comparer position="25">
<img
slot="before"
src="https://images.unsplash.com/photo-1520903074185-8eca362b3dce?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&q=80"
alt="A person sitting on bricks wearing untied boots."
/>
<img
slot="after"
src="https://images.unsplash.com/photo-1520640023173-50a135e35804?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2250&q=80"
alt="A person sitting on a yellow curb tying shoelaces on a boot."
/>
</sl-image-comparer>
```
```jsx:react
import { SlImageComparer } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlImageComparer position={25}>
<img
slot="before"
src="https://images.unsplash.com/photo-1520903074185-8eca362b3dce?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&q=80"
alt="A person sitting on bricks wearing untied boots."
/>
<img
slot="after"
src="https://images.unsplash.com/photo-1520640023173-50a135e35804?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2250&q=80"
alt="A person sitting on a yellow curb tying shoelaces on a boot."
/>
</SlImageComparer>
);
```

48
docs/pages/components/include.md Normal file
View File

@@ -0,0 +1,48 @@
---
meta:
title: Include
description: Includes give you the power to embed external HTML files into the page.
layout: component
---
Included files are asynchronously requested using `window.fetch()`. Requests are cached, so the same file can be included multiple times, but only one request will be made.
The included content will be inserted into the `<sl-include>` element's default slot so it can be easily accessed and styled through the light DOM.
```html:preview
<sl-include src="https://shoelace.style/assets/examples/include.html"></sl-include>
```
```jsx:react
import { SlInclude } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInclude src="https://shoelace.style/assets/examples/include.html" />;
```
## Examples
### Listening for Events
When an include file loads successfully, the `sl-load` event will be emitted. You can listen for this event to add custom loading logic to your includes.
If the request fails, the `sl-error` event will be emitted. In this case, `event.detail.status` will contain the resulting HTTP status code of the request, e.g. 404 (not found).
```html
<sl-include src="https://shoelace.style/assets/examples/include.html"></sl-include>
<script>
const include = document.querySelector('sl-include');
include.addEventListener('sl-load', event => {
if (event.eventPhase === Event.AT_TARGET) {
console.log('Success');
}
});
include.addEventListener('sl-error', event => {
if (event.eventPhase === Event.AT_TARGET) {
console.log('Error', event.detail.status);
}
});
</script>
```

278
docs/pages/components/input.md Normal file
View File

@@ -0,0 +1,278 @@
---
meta:
title: Input
description: Inputs collect data from the user.
layout: component
---
```html:preview
<sl-input></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput />;
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Labels
Use the `label` attribute to give the input an accessible label. For labels that contain HTML, use the `label` slot instead.
```html:preview
<sl-input label="What is your name?"></sl-input>
```
```jsx:react
import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput label="What is your name?" />;
```
### Help Text
Add descriptive help text to an input with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
```html:preview
<sl-input label="Nickname" help-text="What would you like people to call you?"></sl-input>
```
```jsx:react
import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput label="Nickname" help-text="What would you like people to call you?" />;
```
### Placeholders
Use the `placeholder` attribute to add a placeholder.
```html:preview
<sl-input placeholder="Type something"></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput placeholder="Type something" />;
```
### Clearable
Add the `clearable` attribute to add a clear button when the input has content.
```html:preview
<sl-input placeholder="Clearable" clearable></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput placeholder="Clearable" clearable />;
```
### Toggle Password
Add the `password-toggle` attribute to add a toggle button that will show the password when activated.
```html:preview
<sl-input type="password" placeholder="Password Toggle" password-toggle></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput type="password" placeholder="Password Toggle" size="medium" password-toggle />;
```
### Filled Inputs
Add the `filled` attribute to draw a filled input.
```html:preview
<sl-input placeholder="Type something" filled></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput placeholder="Type something" filled />;
```
### Disabled
Use the `disabled` attribute to disable an input.
```html:preview
<sl-input placeholder="Disabled" disabled></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlInput placeholder="Disabled" disabled />;
```
### Sizes
Use the `size` attribute to change an input's size.
```html:preview
<sl-input placeholder="Small" size="small"></sl-input>
<br />
<sl-input placeholder="Medium" size="medium"></sl-input>
<br />
<sl-input placeholder="Large" size="large"></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlInput placeholder="Small" size="small" />
<br />
<SlInput placeholder="Medium" size="medium" />
<br />
<SlInput placeholder="Large" size="large" />
</>
);
```
### Pill
Use the `pill` attribute to give inputs rounded edges.
```html:preview
<sl-input placeholder="Small" size="small" pill></sl-input>
<br />
<sl-input placeholder="Medium" size="medium" pill></sl-input>
<br />
<sl-input placeholder="Large" size="large" pill></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlInput placeholder="Small" size="small" pill />
<br />
<SlInput placeholder="Medium" size="medium" pill />
<br />
<SlInput placeholder="Large" size="large" pill />
</>
);
```
### Input Types
The `type` attribute controls the type of input the browser renders.
```html:preview
<sl-input type="email" placeholder="Email"></sl-input>
<br />
<sl-input type="number" placeholder="Number"></sl-input>
<br />
<sl-input type="date" placeholder="Date"></sl-input>
```
```jsx:react
import { SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlInput type="email" placeholder="Email" />
<br />
<SlInput type="number" placeholder="Number" />
<br />
<SlInput type="date" placeholder="Date" />
</>
);
```
### Prefix & Suffix Icons
Use the `prefix` and `suffix` slots to add icons.
```html:preview
<sl-input placeholder="Small" size="small">
<sl-icon name="house" slot="prefix"></sl-icon>
<sl-icon name="chat" slot="suffix"></sl-icon>
</sl-input>
<br />
<sl-input placeholder="Medium" size="medium">
<sl-icon name="house" slot="prefix"></sl-icon>
<sl-icon name="chat" slot="suffix"></sl-icon>
</sl-input>
<br />
<sl-input placeholder="Large" size="large">
<sl-icon name="house" slot="prefix"></sl-icon>
<sl-icon name="chat" slot="suffix"></sl-icon>
</sl-input>
```
```jsx:react
import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlInput placeholder="Small" size="small">
<SlIcon name="house" slot="prefix"></SlIcon>
<SlIcon name="chat" slot="suffix"></SlIcon>
</SlInput>
<br />
<SlInput placeholder="Medium" size="medium">
<SlIcon name="house" slot="prefix"></SlIcon>
<SlIcon name="chat" slot="suffix"></SlIcon>
</SlInput>
<br />
<SlInput placeholder="Large" size="large">
<SlIcon name="house" slot="prefix"></SlIcon>
<SlIcon name="chat" slot="suffix"></SlIcon>
</SlInput>
</>
);
```
### Customizing Label Position
Use [CSS parts](#css-parts) to customize the way form controls are drawn. This example uses CSS grid to position the label to the left of the control, but the possible orientations are nearly endless. The same technique works for inputs, textareas, radio groups, and similar form controls.
```html:preview
<sl-input class="label-on-left" label="Name" help-text="Enter your name"></sl-input>
<sl-input class="label-on-left" label="Email" type="email" help-text="Enter your email"></sl-input>
<sl-textarea class="label-on-left" label="Bio" help-text="Tell us something about yourself"></sl-textarea>
<style>
.label-on-left {
--label-width: 3.75rem;
--gap-width: 1rem;
}
.label-on-left + .label-on-left {
margin-top: var(--sl-spacing-medium);
}
.label-on-left::part(form-control) {
display: grid;
grid: auto / var(--label-width) 1fr;
gap: var(--sl-spacing-3x-small) var(--gap-width);
align-items: center;
}
.label-on-left::part(form-control-label) {
text-align: right;
}
.label-on-left::part(form-control-help-text) {
grid-column-start: 2;
}
</style>
```

235
docs/pages/components/menu-item.md Normal file
View File

@@ -0,0 +1,235 @@
---
meta:
title: Menu Item
description: Menu items provide options for the user to pick from in a menu.
layout: component
---
```html:preview
<sl-menu style="max-width: 200px;">
<sl-menu-item>Option 1</sl-menu-item>
<sl-menu-item>Option 2</sl-menu-item>
<sl-menu-item>Option 3</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item type="checkbox" checked>Checkbox</sl-menu-item>
<sl-menu-item disabled>Disabled</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item>
Prefix Icon
<sl-icon slot="prefix" name="gift"></sl-icon>
</sl-menu-item>
<sl-menu-item>
Suffix Icon
<sl-icon slot="suffix" name="heart"></sl-icon>
</sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlDivider, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu style={{ maxWidth: '200px' }}>
<SlMenuItem>Option 1</SlMenuItem>
<SlMenuItem>Option 2</SlMenuItem>
<SlMenuItem>Option 3</SlMenuItem>
<SlDivider />
<SlMenuItem type="checkbox" checked>
Checkbox
</SlMenuItem>
<SlMenuItem disabled>Disabled</SlMenuItem>
<SlDivider />
<SlMenuItem>
Prefix Icon
<SlIcon slot="prefix" name="gift" />
</SlMenuItem>
<SlMenuItem>
Suffix Icon
<SlIcon slot="suffix" name="heart" />
</SlMenuItem>
</SlMenu>
);
```
{% endraw %}
## Examples
### Disabled
Add the `disabled` attribute to disable the menu item so it cannot be selected.
```html:preview
<sl-menu style="max-width: 200px;">
<sl-menu-item>Option 1</sl-menu-item>
<sl-menu-item disabled>Option 2</sl-menu-item>
<sl-menu-item>Option 3</sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu style={{ maxWidth: '200px' }}>
<SlMenuItem>Option 1</SlMenuItem>
<SlMenuItem disabled>Option 2</SlMenuItem>
<SlMenuItem>Option 3</SlMenuItem>
</SlMenu>
);
```
{% endraw %}
### Prefix & Suffix
Add content to the start and end of menu items using the `prefix` and `suffix` slots.
```html:preview
<sl-menu style="max-width: 200px;">
<sl-menu-item>
<sl-icon slot="prefix" name="house"></sl-icon>
Home
</sl-menu-item>
<sl-menu-item>
<sl-icon slot="prefix" name="envelope"></sl-icon>
Messages
<sl-badge slot="suffix" variant="primary" pill>12</sl-badge>
</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item>
<sl-icon slot="prefix" name="gear"></sl-icon>
Settings
</sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlBadge, SlDivider, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu style={{ maxWidth: '200px' }}>
<SlMenuItem>
<SlIcon slot="prefix" name="house" />
Home
</SlMenuItem>
<SlMenuItem>
<SlIcon slot="prefix" name="envelope" />
Messages
<SlBadge slot="suffix" variant="primary" pill>
12
</SlBadge>
</SlMenuItem>
<SlDivider />
<SlMenuItem>
<SlIcon slot="prefix" name="gear" />
Settings
</SlMenuItem>
</SlMenu>
);
```
{% endraw %}
### Checkbox Menu Items
Set the `type` attribute to `checkbox` to create a menu item that will toggle on and off when selected. You can use the `checked` attribute to set the initial state.
Checkbox menu items are visually indistinguishable from regular menu items. Their ability to be toggled is primarily inferred from context, much like you'd find in the menu of a native app.
```html:preview
<sl-menu style="max-width: 200px;">
<sl-menu-item type="checkbox">Autosave</sl-menu-item>
<sl-menu-item type="checkbox" checked>Check Spelling</sl-menu-item>
<sl-menu-item type="checkbox">Word Wrap</sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu style={{ maxWidth: '200px' }}>
<SlMenuItem type="checkbox">Autosave</SlMenuItem>
<SlMenuItem type="checkbox" checked>
Check Spelling
</SlMenuItem>
<SlMenuItem type="checkbox">Word Wrap</SlMenuItem>
</SlMenu>
);
```
{% endraw %}
### Value & Selection
The `value` attribute can be used to assign a hidden value, such as a unique identifier, to a menu item. When an item is selected, the `sl-select` event will be emitted and a reference to the item will be available at `event.detail.item`. You can use this reference to access the selected item's value, its checked state, and more.
```html:preview
<sl-menu class="menu-value" style="max-width: 200px;">
<sl-menu-item value="opt-1">Option 1</sl-menu-item>
<sl-menu-item value="opt-2">Option 2</sl-menu-item>
<sl-menu-item value="opt-3">Option 3</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item type="checkbox" value="opt-4">Checkbox 4</sl-menu-item>
<sl-menu-item type="checkbox" value="opt-5">Checkbox 5</sl-menu-item>
<sl-menu-item type="checkbox" value="opt-6">Checkbox 6</sl-menu-item>
</sl-menu>
<script>
const menu = document.querySelector('.menu-value');
menu.addEventListener('sl-select', event => {
const item = event.detail.item;
// Log value
if (item.type === 'checkbox') {
console.log(`Selected value: ${item.value} (${item.checked ? 'checked' : 'unchecked'})`);
} else {
console.log(`Selected value: ${item.value}`);
}
});
</script>
```
{% raw %}
```jsx:react
import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleSelect(event) {
const item = event.detail.item;
// Toggle checked state
item.checked = !item.checked;
// Log value
console.log(`Selected value: ${item.value}`);
}
return (
<SlMenu style={{ maxWidth: '200px' }} onSlSelect={handleSelect}>
<SlMenuItem value="opt-1">Option 1</SlMenuItem>
<SlMenuItem value="opt-2">Option 2</SlMenuItem>
<SlMenuItem value="opt-3">Option 3</SlMenuItem>
</SlMenu>
);
};
```
{% endraw %}

42
docs/pages/components/menu-label.md Normal file
View File

@@ -0,0 +1,42 @@
---
meta:
title: Menu Label
description: Menu labels are used to describe a group of menu items.
layout: component
---
```html:preview
<sl-menu style="max-width: 200px;">
<sl-menu-label>Fruits</sl-menu-label>
<sl-menu-item value="apple">Apple</sl-menu-item>
<sl-menu-item value="banana">Banana</sl-menu-item>
<sl-menu-item value="orange">Orange</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-label>Vegetables</sl-menu-label>
<sl-menu-item value="broccoli">Broccoli</sl-menu-item>
<sl-menu-item value="carrot">Carrot</sl-menu-item>
<sl-menu-item value="zucchini">Zucchini</sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlDivider, SlMenu, SlMenuLabel, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu style={{ maxWidth: '200px' }}>
<SlMenuLabel>Fruits</SlMenuLabel>
<SlMenuItem value="apple">Apple</SlMenuItem>
<SlMenuItem value="banana">Banana</SlMenuItem>
<SlMenuItem value="orange">Orange</SlMenuItem>
<SlDivider />
<SlMenuLabel>Vegetables</SlMenuLabel>
<SlMenuItem value="broccoli">Broccoli</SlMenuItem>
<SlMenuItem value="carrot">Carrot</SlMenuItem>
<SlMenuItem value="zucchini">Zucchini</SlMenuItem>
</SlMenu>
);
```
{% endraw %}

44
docs/pages/components/menu.md Normal file
View File

@@ -0,0 +1,44 @@
---
meta:
title: Menu
description: Menus provide a list of options for the user to choose from.
layout: component
---
You can use [menu items](/components/menu-item), [menu labels](/components/menu-label), and [dividers](/components/divider) to compose a menu. Menus support keyboard interactions, including type-to-select an option.
```html:preview
<sl-menu style="max-width: 200px;">
<sl-menu-item value="undo">Undo</sl-menu-item>
<sl-menu-item value="redo">Redo</sl-menu-item>
<sl-divider></sl-divider>
<sl-menu-item value="cut">Cut</sl-menu-item>
<sl-menu-item value="copy">Copy</sl-menu-item>
<sl-menu-item value="paste">Paste</sl-menu-item>
<sl-menu-item value="delete">Delete</sl-menu-item>
</sl-menu>
```
{% raw %}
```jsx:react
import { SlDivider, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlMenu style={{ maxWidth: '200px' }}>
<SlMenuItem value="undo">Undo</SlMenuItem>
<SlMenuItem value="redo">Redo</SlMenuItem>
<SlDivider />
<SlMenuItem value="cut">Cut</SlMenuItem>
<SlMenuItem value="copy">Copy</SlMenuItem>
<SlMenuItem value="paste">Paste</SlMenuItem>
<SlMenuItem value="delete">Delete</SlMenuItem>
</SlMenu>
);
```
{% endraw %}
:::tip
Menus are intended for system menus (dropdown menus, select menus, context menus, etc.). They should not be mistaken for navigation menus which serve a different purpose and have a different semantic meaning. If you're building navigation, use `<nav>` and `<a>` elements instead.
:::

194
docs/pages/components/mutation-observer.md Normal file
View File

@@ -0,0 +1,194 @@
---
meta:
title: Mutation Observer
description: The Mutation Observer component offers a thin, declarative interface to the MutationObserver API.
layout: component
---
The mutation observer will report changes to the content it wraps through the `sl-mutation` event. When emitted, a collection of [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects will be attached to `event.detail` that contains information about how it changed.
```html:preview
<div class="mutation-overview">
<sl-mutation-observer attr="variant">
<sl-button variant="primary">Click to mutate</sl-button>
</sl-mutation-observer>
<br />
👆 Click the button and watch the console
<script>
const container = document.querySelector('.mutation-overview');
const mutationObserver = container.querySelector('sl-mutation-observer');
const button = container.querySelector('sl-button');
const variants = ['primary', 'success', 'neutral', 'warning', 'danger'];
let clicks = 0;
// Change the button's variant attribute
button.addEventListener('click', () => {
clicks++;
button.setAttribute('variant', variants[clicks % variants.length]);
});
// Log mutations
mutationObserver.addEventListener('sl-mutation', event => {
console.log(event.detail);
});
</script>
<style>
.mutation-overview sl-button {
margin-bottom: 1rem;
}
</style>
</div>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlMutationObserver } from '@shoelace-style/shoelace/dist/react';
const css = `
.resize-observer-overview div {
display: flex;
border: solid 2px var(--sl-input-border-color);
align-items: center;
justify-content: center;
text-align: center;
padding: 4rem 2rem;
}
`;
const variants = ['primary', 'success', 'neutral', 'warning', 'danger'];
let clicks = 0;
const App = () => {
const [variant, setVariant] = useState('primary');
function handleClick() {
clicks++;
setVariant(variants[clicks % variants.length]);
}
return (
<>
<SlMutationObserver attr="*" onSlMutation={event => console.log(event.detail)}>
<SlButton variant={variant} onClick={handleClick}>
Click to mutate
</SlButton>
</SlMutationObserver>
<style>{css}</style>
</>
);
};
```
:::tip
When you create a mutation observer, you must indicate what changes it should respond to by including at least one of `attr`, `child-list`, or `char-data`. If you don't specify at least one of these attributes, no mutation events will be emitted.
:::
## Examples
### Child List
Use the `child-list` attribute to watch for new child elements that are added or removed.
```html:preview
<div class="mutation-child-list">
<sl-mutation-observer child-list>
<div class="buttons">
<sl-button variant="primary">Add button</sl-button>
</div>
</sl-mutation-observer>
👆 Add and remove buttons and watch the console
<script>
const container = document.querySelector('.mutation-child-list');
const mutationObserver = container.querySelector('sl-mutation-observer');
const buttons = container.querySelector('.buttons');
const button = container.querySelector('sl-button[variant="primary"]');
let i = 0;
// Add a button
button.addEventListener('click', () => {
const button = document.createElement('sl-button');
button.textContent = ++i;
buttons.append(button);
});
// Remove a button
buttons.addEventListener('click', event => {
const target = event.target.closest('sl-button:not([variant="primary"])');
event.stopPropagation();
if (target) {
target.remove();
}
});
// Log mutations
mutationObserver.addEventListener('sl-mutation', event => {
console.log(event.detail);
});
</script>
<style>
.mutation-child-list .buttons {
display: flex;
gap: 0.25rem;
flex-wrap: wrap;
margin-bottom: 1rem;
}
</style>
</div>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlMutationObserver } from '@shoelace-style/shoelace/dist/react';
const css = `
.mutation-child-list .buttons {
display: flex;
gap: .25rem;
flex-wrap: wrap;
margin-bottom: 1rem;
}
`;
let buttonCount = 0;
const App = () => {
const [buttonIds, setButtonIds] = useState([]);
function addButton() {
setButtonIds([...buttonIds, ++buttonCount]);
}
function removeButton(id) {
setButtonIds(buttonIds.filter(i => i !== id));
}
return (
<>
<div className="mutation-child-list">
<SlMutationObserver child-list onSlMutation={event => console.log(event.detail)}>
<div className="buttons">
<SlButton variant="primary" onClick={addButton}>
Add button
</SlButton>
{buttonIds.map(id => (
<SlButton key={id} variant="default" onClick={() => removeButton(id)}>
{id}
</SlButton>
))}
</div>
</SlMutationObserver>
</div>
👆 Add and remove buttons and watch the console
<style>{css}</style>
</>
);
};
```

80
docs/pages/components/option.md Normal file
View File

@@ -0,0 +1,80 @@
---
meta:
title: Option
description: Options define the selectable items within various form controls such as select.
layout: component
---
```html:preview
<sl-select label="Select one">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
## Examples
### Disabled
Use the `disabled` attribute to disable an option and prevent it from being selected.
```html:preview
<sl-select label="Select one">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2" disabled>Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2" disabled>
Option 2
</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Prefix & Suffix
Add icons to the start and end of menu items using the `prefix` and `suffix` slots.
```html:preview
<sl-select label="Select one">
<sl-option value="option-1">
<sl-icon slot="prefix" name="envelope"></sl-icon>
Email
<sl-icon slot="suffix" name="patch-check"></sl-icon>
</sl-option>
<sl-option value="option-2">
<sl-icon slot="prefix" name="telephone"></sl-icon>
Phone
<sl-icon slot="suffix" name="patch-check"></sl-icon>
</sl-option>
<sl-option value="option-3">
<sl-icon slot="prefix" name="chat-dots"></sl-icon>
Chat
<sl-icon slot="suffix" name="patch-check"></sl-icon>
</sl-option>
</sl-select>
```

1513
docs/pages/components/popup.md Normal file
View File

File diff suppressed because it is too large Load Diff

127
docs/pages/components/progress-bar.md Normal file
View File

@@ -0,0 +1,127 @@
---
meta:
title: Progress Bar
description: Progress bars are used to show the status of an ongoing operation.
layout: component
---
```html:preview
<sl-progress-bar value="50"></sl-progress-bar>
```
```jsx:react
import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressBar value={50} />;
```
## Examples
### Labels
Use the `label` attribute to label the progress bar and tell assistive devices how to announce it.
```html:preview
<sl-progress-bar value="50" label="Upload progress"></sl-progress-bar>
```
```jsx:react
import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressBar value="50" label="Upload progress" />;
```
### Custom Height
Use the `--height` custom property to set the progress bar's height.
```html:preview
<sl-progress-bar value="50" style="--height: 6px;"></sl-progress-bar>
```
{% raw %}
```jsx:react
import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressBar value={50} style={{ '--height': '6px' }} />;
```
{% endraw %}
### Showing Values
Use the default slot to show a value.
```html:preview
<sl-progress-bar value="50" class="progress-bar-values">50%</sl-progress-bar>
<br />
<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>
<script>
const progressBar = document.querySelector('.progress-bar-values');
const subtractButton = progressBar.nextElementSibling.nextElementSibling;
const addButton = subtractButton.nextElementSibling;
addButton.addEventListener('click', () => {
const value = Math.min(100, progressBar.value + 10);
progressBar.value = value;
progressBar.textContent = `${value}%`;
});
subtractButton.addEventListener('click', () => {
const value = Math.max(0, progressBar.value - 10);
progressBar.value = value;
progressBar.textContent = `${value}%`;
});
</script>
```
```jsx:react
import { useState } from 'react';
import { SlButton, SlIcon, SlProgressBar } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [value, setValue] = useState(50);
function adjustValue(amount) {
let newValue = value + amount;
if (newValue < 0) newValue = 0;
if (newValue > 100) newValue = 100;
setValue(newValue);
}
return (
<>
<SlProgressBar value={value}>{value}%</SlProgressBar>
<br />
<SlButton circle onClick={() => adjustValue(-10)}>
<SlIcon name="dash" label="Decrease" />
</SlButton>
<SlButton circle onClick={() => adjustValue(10)}>
<SlIcon name="plus" label="Increase" />
</SlButton>
</>
);
};
```
### Indeterminate
The `indeterminate` attribute can be used to inform the user that the operation is pending, but its status cannot currently be determined. In this state, `value` is ignored and the label, if present, will not be shown.
```html:preview
<sl-progress-bar indeterminate></sl-progress-bar>
```
```jsx:react
import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressBar indeterminate />;
```

169
docs/pages/components/progress-ring.md Normal file
View File

@@ -0,0 +1,169 @@
---
meta:
title: Progress Ring
description: Progress rings are used to show the progress of a determinate operation in a circular fashion.
layout: component
---
```html:preview
<sl-progress-ring value="25"></sl-progress-ring>
```
```jsx:react
import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressRing value="25" />;
```
## Examples
### Size
Use the `--size` custom property to set the diameter of the progress ring.
```html:preview
<sl-progress-ring value="50" style="--size: 200px;"></sl-progress-ring>
```
{% raw %}
```jsx:react
import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressRing value="50" style={{ '--size': '200px' }} />;
```
{% endraw %}
### Track and Indicator Width
Use the `--track-width` and `--indicator-width` custom properties to set the width of the progress ring's track and indicator.
```html:preview
<sl-progress-ring value="50" style="--track-width: 6px; --indicator-width: 12px;"></sl-progress-ring>
```
{% raw %}
```jsx:react
import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressRing value="50" style={{ '--track-width': '6px', '--indicator-width': '12px' }} />;
```
{% endraw %}
### Colors
To change the color, use the `--track-color` and `--indicator-color` custom properties.
```html:preview
<sl-progress-ring
value="50"
style="
--track-color: pink;
--indicator-color: deeppink;
"
></sl-progress-ring>
```
{% raw %}
```jsx:react
import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlProgressRing
value="50"
style={{
'--track-color': 'pink',
'--indicator-color': 'deeppink'
}}
/>
);
```
{% endraw %}
### Labels
Use the `label` attribute to label the progress ring and tell assistive devices how to announce it.
```html:preview
<sl-progress-ring value="50" label="Upload progress"></sl-progress-ring>
```
```jsx:react
import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlProgressRing value="50" label="Upload progress" />;
```
### Showing Values
Use the default slot to show a label inside the progress ring.
```html:preview
<sl-progress-ring value="50" class="progress-ring-values" style="margin-bottom: .5rem;">50%</sl-progress-ring>
<br />
<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>
<script>
const progressRing = document.querySelector('.progress-ring-values');
const subtractButton = progressRing.nextElementSibling.nextElementSibling;
const addButton = subtractButton.nextElementSibling;
addButton.addEventListener('click', () => {
const value = Math.min(100, progressRing.value + 10);
progressRing.value = value;
progressRing.textContent = `${value}%`;
});
subtractButton.addEventListener('click', () => {
const value = Math.max(0, progressRing.value - 10);
progressRing.value = value;
progressRing.textContent = `${value}%`;
});
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlButton, SlIcon, SlProgressRing } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [value, setValue] = useState(50);
function adjustValue(amount) {
let newValue = value + amount;
if (newValue < 0) newValue = 0;
if (newValue > 100) newValue = 100;
setValue(newValue);
}
return (
<>
<SlProgressRing value={value} style={{ marginBottom: '.5rem' }}>
{value}%
</SlProgressRing>
<br />
<SlButton circle onClick={() => adjustValue(-10)}>
<SlIcon name="dash" label="Decrease" />
</SlButton>
<SlButton circle onClick={() => adjustValue(10)}>
<SlIcon name="plus" label="Increase" />
</SlButton>
</>
);
};
```
{% endraw %}

162
docs/pages/components/qr-code.md Normal file
View File

@@ -0,0 +1,162 @@
---
meta:
title: QR Code
description: Generates a QR code and renders it using the Canvas API.
layout: component
---
QR codes are useful for providing small pieces of information to users who can quickly scan them with a smartphone. Most smartphones have built-in QR code scanners, so simply pointing the camera at a QR code will decode it and allow the user to visit a website, dial a phone number, read a message, etc.
```html:preview
<div class="qr-overview">
<sl-qr-code value="https://shoelace.style/" label="Scan this code to visit Shoelace on the web!"></sl-qr-code>
<br />
<sl-input maxlength="255" clearable label="Value"></sl-input>
</div>
<script>
const container = document.querySelector('.qr-overview');
const qrCode = container.querySelector('sl-qr-code');
const input = container.querySelector('sl-input');
customElements.whenDefined('sl-qr-code').then(() => {
input.value = qrCode.value;
input.addEventListener('sl-input', () => (qrCode.value = input.value));
});
</script>
<style>
.qr-overview {
max-width: 256px;
}
.qr-overview sl-input {
margin-top: 1rem;
}
</style>
```
```jsx:react
import { useState } from 'react';
import { SlQrCode, SlInput } from '@shoelace-style/shoelace/dist/react';
const css = `
.qr-overview {
max-width: 256px;
}
.qr-overview sl-input {
margin-top: 1rem;
}
`;
const App = () => {
const [value, setValue] = useState('https://shoelace.style/');
return (
<>
<div className="qr-overview">
<SlQrCode value={value} label="Scan this code to visit Shoelace on the web!" />
<br />
<SlInput maxlength="255" clearable onInput={event => setValue(event.target.value)} />
</div>
<style>{css}</style>
</>
);
};
```
## Examples
### Colors
Use the `fill` and `background` attributes to modify the QR code's colors. You should always ensure good contrast for optimal compatibility with QR code scanners.
```html:preview
<sl-qr-code value="https://shoelace.style/" fill="deeppink" background="white"></sl-qr-code>
```
```jsx:react
import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlQrCode value="https://shoelace.style/" fill="deeppink" background="white" />;
```
### Size
Use the `size` attribute to change the size of the QR code.
```html:preview
<sl-qr-code value="https://shoelace.style/" size="64"></sl-qr-code>
```
```jsx:react
import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlQrCode value="https://shoelace.style/" size="64" />;
```
### Radius
Create a rounded effect with the `radius` attribute.
```html:preview
<sl-qr-code value="https://shoelace.style/" radius="0.5"></sl-qr-code>
```
```jsx:react
import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlQrCode value="https://shoelace.style/" radius="0.5" />;
```
### Error Correction
QR codes can be rendered with various levels of [error correction](https://www.qrcode.com/en/about/error_correction.html) that can be set using the `error-correction` attribute. This example generates four codes with the same value using different error correction levels.
```html:preview
<div class="qr-error-correction">
<sl-qr-code value="https://shoelace.style/" error-correction="L"></sl-qr-code>
<sl-qr-code value="https://shoelace.style/" error-correction="M"></sl-qr-code>
<sl-qr-code value="https://shoelace.style/" error-correction="Q"></sl-qr-code>
<sl-qr-code value="https://shoelace.style/" error-correction="H"></sl-qr-code>
</div>
<style>
.qr-error-correction {
display: flex;
flex-wrap: wrap;
gap: 1rem;
}
</style>
```
```jsx:react
import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
const css = `
.qr-error-correction {
display: flex;
flex-wrap: wrap;
gap: 1rem;
}
`;
const App = () => {
return (
<>
<div className="qr-error-correction">
<SlQrCode value="https://shoelace.style/" error-correction="L" />
<SlQrCode value="https://shoelace.style/" error-correction="M" />
<SlQrCode value="https://shoelace.style/" error-correction="Q" />
<SlQrCode value="https://shoelace.style/" error-correction="H" />
</div>
<style>{css}</style>
</>
);
};
```

296
docs/pages/components/radio-button.md Normal file
View File

@@ -0,0 +1,296 @@
---
meta:
title: Radio Button
description: Radios buttons allow the user to select a single option from a group using a button-like control.
layout: component
---
Radio buttons are designed to be used with [radio groups](/components/radio-group). When a radio button has focus, the arrow keys can be used to change the selected option just like standard radio controls.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button value="1">Option 1</sl-radio-button>
<sl-radio-button value="2">Option 2</sl-radio-button>
<sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton value="1">Option 1</SlRadioButton>
<SlRadioButton value="2">Option 2</SlRadioButton>
<SlRadioButton value="3">Option 3</SlRadioButton>
</SlRadioGroup>
);
```
## Examples
### Checked States
To set the initial value and checked state, use the `value` attribute on the containing radio group.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button value="1">Option 1</sl-radio-button>
<sl-radio-button value="2">Option 2</sl-radio-button>
<sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton value="1">Option 1</SlRadioButton>
<SlRadioButton value="2">Option 2</SlRadioButton>
<SlRadioButton value="3">Option 3</SlRadioButton>
</SlRadioGroup>
);
```
### Disabled
Use the `disabled` attribute to disable a radio button.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button value="1">Option 1</sl-radio-button>
<sl-radio-button value="2" disabled>Option 2</sl-radio-button>
<sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton value="1">Option 1</SlRadioButton>
<SlRadioButton value="2" disabled>
Option 2
</SlRadioButton>
<SlRadioButton value="3">Option 3</SlRadioButton>
</SlRadioGroup>
);
```
### Sizes
Use the `size` attribute to change a radio button's size.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button size="small" value="1">Option 1</sl-radio-button>
<sl-radio-button size="small" value="2">Option 2</sl-radio-button>
<sl-radio-button size="small" value="3">Option 3</sl-radio-button>
</sl-radio-group>
<br />
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button size="medium" value="1">Option 1</sl-radio-button>
<sl-radio-button size="medium" value="2">Option 2</sl-radio-button>
<sl-radio-button size="medium" value="3">Option 3</sl-radio-button>
</sl-radio-group>
<br />
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button size="large" value="1">Option 1</sl-radio-button>
<sl-radio-button size="large" value="2">Option 2</sl-radio-button>
<sl-radio-button size="large" value="3">Option 3</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton size="small" value="1">Option 1</SlRadioButton>
<SlRadioButton size="small" value="2">Option 2</SlRadioButton>
<SlRadioButton size="small" value="3">Option 3</SlRadioButton>
</SlRadioGroup>
<br />
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton size="medium" value="1">Option 1</SlRadioButton>
<SlRadioButton size="medium" value="2">Option 2</SlRadioButton>
<SlRadioButton size="medium" value="3">Option 3</SlRadioButton>
</SlRadioGroup>
<br />
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton size="large" value="1">Option 1</SlRadioButton>
<SlRadioButton size="large" value="2">Option 2</SlRadioButton>
<SlRadioButton size="large" value="3">Option 3</SlRadioButton>
</SlRadioGroup>
);
```
### Pill Buttons
Use the `pill` attribute to give radio buttons rounded edges.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button pill size="small" value="1">Option 1</sl-radio-button>
<sl-radio-button pill size="small" value="2">Option 2</sl-radio-button>
<sl-radio-button pill size="small" value="3">Option 3</sl-radio-button>
</sl-radio-group>
<br />
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button pill size="medium" value="1">Option 1</sl-radio-button>
<sl-radio-button pill size="medium" value="2">Option 2</sl-radio-button>
<sl-radio-button pill size="medium" value="3">Option 3</sl-radio-button>
</sl-radio-group>
<br />
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button pill size="large" value="1">Option 1</sl-radio-button>
<sl-radio-button pill size="large" value="2">Option 2</sl-radio-button>
<sl-radio-button pill size="large" value="3">Option 3</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton pill size="small" value="1">Option 1</SlRadioButton>
<SlRadioButton pill size="small" value="2">Option 2</SlRadioButton>
<SlRadioButton pill size="small" value="3">Option 3</SlRadioButton>
</SlRadioGroup>
<br />
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton pill size="medium" value="1">Option 1</SlRadioButton>
<SlRadioButton pill size="medium" value="2">Option 2</SlRadioButton>
<SlRadioButton pill size="medium" value="3">Option 3</SlRadioButton>
</SlRadioGroup>
<br />
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton pill size="large" value="1">Option 1</SlRadioButton>
<SlRadioButton pill size="large" value="2">Option 2</SlRadioButton>
<SlRadioButton pill size="large" value="3">Option 3</SlRadioButton>
</SlRadioGroup>
);
```
### Prefix and Suffix Icons
Use the `prefix` and `suffix` slots to add icons.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio-button value="1">
<sl-icon slot="prefix" name="archive"></sl-icon>
Option 1
</sl-radio-button>
<sl-radio-button value="2">
<sl-icon slot="suffix" name="bag"></sl-icon>
Option 2
</sl-radio-button>
<sl-radio-button value="3">
<sl-icon slot="prefix" name="gift"></sl-icon>
<sl-icon slot="suffix" name="cart"></sl-icon>
Option 3
</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton value="1">
<SlIcon slot="prefix" name="archive" />
Option 1
</SlRadioButton>
<SlRadioButton value="2">
<SlIcon slot="suffix" name="bag" />
Option 2
</SlRadioButton>
<SlRadioButton value="3">
<SlIcon slot="prefix" name="gift" />
<SlIcon slot="suffix" name="cart" />
Option 3
</SlRadioButton>
</SlRadioGroup>
);
```
### Buttons with Icons
You can omit button labels and use icons instead. Make sure to set a `label` attribute on each icon so screen readers will announce each option correctly.
```html:preview
<sl-radio-group label="Select an option" name="a" value="neutral">
<sl-radio-button value="angry">
<sl-icon name="emoji-angry" label="Angry"></sl-icon>
</sl-radio-button>
<sl-radio-button value="sad">
<sl-icon name="emoji-frown" label="Sad"></sl-icon>
</sl-radio-button>
<sl-radio-button value="neutral">
<sl-icon name="emoji-neutral" label="Neutral"></sl-icon>
</sl-radio-button>
<sl-radio-button value="happy">
<sl-icon name="emoji-smile" label="Happy"></sl-icon>
</sl-radio-button>
<sl-radio-button value="laughing">
<sl-icon name="emoji-laughing" label="Laughing"></sl-icon>
</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="neutral">
<SlRadioButton value="angry">
<SlIcon name="emoji-angry" label="Angry" />
</SlRadioButton>
<SlRadioButton value="sad">
<SlIcon name="emoji-frown" label="Sad" />
</SlRadioButton>
<SlRadioButton value="neutral">
<SlIcon name="emoji-neutral" label="Neutral" />
</SlRadioButton>
<SlRadioButton value="happy">
<SlIcon name="emoji-smile" label="Happy" />
</SlRadioButton>
<SlRadioButton value="laughing">
<SlIcon name="emoji-laughing" label="Laughing" />
</SlRadioButton>
</SlRadioGroup>
);
```

282
docs/pages/components/radio-group.md Normal file
View File

@@ -0,0 +1,282 @@
---
meta:
title: Radio Group
description: Radio groups are used to group multiple radios or radio buttons so they function as a single form control.
layout: component
---
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio value="1">Option 1</sl-radio>
<sl-radio value="2">Option 2</sl-radio>
<sl-radio value="3">Option 3</sl-radio>
</sl-radio-group>
```
```jsx:react
import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadio value="1">Option 1</SlRadio>
<SlRadio value="2">Option 2</SlRadio>
<SlRadio value="3">Option 3</SlRadio>
</SlRadioGroup>
);
```
## Examples
### Help Text
Add descriptive help text to a radio group with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
```html:preview
<sl-radio-group label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
<sl-radio value="1">Option 1</sl-radio>
<sl-radio value="2">Option 2</sl-radio>
<sl-radio value="3">Option 3</sl-radio>
</sl-radio-group>
```
```jsx:react
import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
<SlRadio value="1">Option 1</SlRadio>
<SlRadio value="2">Option 2</SlRadio>
<SlRadio value="3">Option 3</SlRadio>
</SlRadioGroup>
);
```
### Radio Buttons
[Radio buttons](/components/radio-button) offer an alternate way to display radio controls. In this case, an internal [button group](/components/button-group) is used to group the buttons into a single, cohesive control.
```html:preview
<sl-radio-group label="Select an option" help-text="Select an option that makes you proud." name="a" value="1">
<sl-radio-button value="1">Option 1</sl-radio-button>
<sl-radio-button value="2">Option 2</sl-radio-button>
<sl-radio-button value="3">Option 3</sl-radio-button>
</sl-radio-group>
```
```jsx:react
import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadioButton value="1">Option 1</SlRadioButton>
<SlRadioButton value="2">Option 2</SlRadioButton>
<SlRadioButton value="3">Option 3</SlRadioButton>
</SlRadioGroup>
);
```
### Disabling Options
Radios and radio buttons can be disabled by adding the `disabled` attribute to the respective options inside the radio group.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio value="1">Option 1</sl-radio>
<sl-radio value="2" disabled>Option 2</sl-radio>
<sl-radio value="3">Option 3</sl-radio>
</sl-radio-group>
```
```jsx:react
import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadio value="1">Option 1</SlRadio>
<SlRadio value="2" disabled>
Option 2
</SlRadio>
<SlRadio value="3">Option 3</SlRadio>
</SlRadioGroup>
);
```
### Sizing Options
The size of [Radios](/components/radio) and [Radio Buttons](/components/radio-buttons) will be determined by the Radio Group's `size` attribute.
```html preview
<sl-radio-group label="Select an option" size="medium" value="medium" class="radio-group-size">
<sl-radio value="small">Small</sl-radio>
<sl-radio value="medium">Medium</sl-radio>
<sl-radio value="large">Large</sl-radio>
</sl-radio-group>
<script>
const radioGroup = document.querySelector('.radio-group-size');
radioGroup.addEventListener('sl-change', () => {
radioGroup.size = radioGroup.value;
});
</script>
```
```jsx react
import { useState } from 'react';
import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [size, setSize] = useState('medium');
return (
<>
<SlRadioGroup
label="Select an option"
size={size}
value={size}
class="radio-group-size"
onSlChange={event => setSize(event.target.value)}
>
<SlRadio value="small">Small</SlRadio>
<SlRadio value="medium">Medium</SlRadio>
<SlRadio value="large">Large</SlRadio>
</SlRadioGroup>
</>
);
};
```
:::tip
[Radios](/components/radio) and [Radio Buttons](/components/radio-button) also have a `size` attribute. This can be useful in certain compositions, but it will be ignored when used inside of a Radio Group.
:::
### Validation
Setting the `required` attribute to make selecting an option mandatory. If a value has not been selected, it will prevent the form from submitting and display an error message.
```html:preview
<form class="validation">
<sl-radio-group label="Select an option" name="a" required>
<sl-radio value="1">Option 1</sl-radio>
<sl-radio value="2">Option 2</sl-radio>
<sl-radio value="3">Option 3</sl-radio>
</sl-radio-group>
<br />
<sl-button type="submit" variant="primary">Submit</sl-button>
</form>
<script>
const form = document.querySelector('.validation');
// Handle form submit
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
</script>
```
```jsx:react
import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleSubmit(event) {
event.preventDefault();
alert('All fields are valid!');
}
return (
<form class="custom-validity" onSubmit={handleSubmit}>
<SlRadioGroup label="Select an option" name="a" required onSlChange={handleChange}>
<SlRadio value="1">
Option 1
</SlRadio>
<SlRadiovalue="2">
Option 2
</SlRadio>
<SlRadio value="3">
Option 3
</SlRadio>
</SlRadioGroup>
<br />
<SlButton type="submit" variant="primary">
Submit
</SlButton>
</form>
);
};
```
### Custom Validity
Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
```html:preview
<form class="custom-validity">
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio value="1">Not me</sl-radio>
<sl-radio value="2">Me neither</sl-radio>
<sl-radio value="3">Choose me</sl-radio>
</sl-radio-group>
<br />
<sl-button type="submit" variant="primary">Submit</sl-button>
</form>
<script>
const form = document.querySelector('.custom-validity');
const radioGroup = form.querySelector('sl-radio-group');
const errorMessage = 'You must choose the last option';
// Set initial validity as soon as the element is defined
customElements.whenDefined('sl-radio').then(() => {
radioGroup.setCustomValidity(errorMessage);
});
// Update validity when a selection is made
form.addEventListener('sl-change', () => {
const isValid = radioGroup.value === '3';
radioGroup.setCustomValidity(isValid ? '' : errorMessage);
});
// Handle form submit
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
</script>
```
```jsx:react
import { useEffect, useRef } from 'react';
import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const radioGroup = useRef(null);
const errorMessage = 'You must choose this option';
function handleChange() {
radioGroup.current.setCustomValidity(radioGroup.current.value === '3' ? '' : errorMessage);
}
function handleSubmit(event) {
event.preventDefault();
alert('All fields are valid!');
}
useEffect(() => {
radio.current.setCustomValidity(errorMessage);
}, []);
return (
<form class="custom-validity" onSubmit={handleSubmit}>
<SlRadioGroup ref={radioGroup} label="Select an option" name="a" value="1" onSlChange={handleChange}>
<SlRadio value="1">Not me</SlRadio>
<SlRadio value="2">Me neither</SlRadio>
<SlRadio value="3">Choose me</SlRadio>
</SlRadioGroup>
<br />
<SlButton type="submit" variant="primary">
Submit
</SlButton>
</form>
);
};
```

142
docs/pages/components/radio.md Normal file
View File

@@ -0,0 +1,142 @@
---
meta:
title: Radio
description: Radios allow the user to select a single option from a group.
layout: component
---
Radios are designed to be used with [radio groups](/components/radio-group).
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio value="1">Option 1</sl-radio>
<sl-radio value="2">Option 2</sl-radio>
<sl-radio value="3">Option 3</sl-radio>
</sl-radio-group>
```
```jsx:react
import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadio value="1">Option 1</SlRadio>
<SlRadio value="2">Option 2</SlRadio>
<SlRadio value="3">Option 3</SlRadio>
</SlRadioGroup>
);
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Initial Value
To set the initial value and checked state, use the `value` attribute on the containing radio group.
```html:preview
<sl-radio-group label="Select an option" name="a" value="3">
<sl-radio value="1">Option 1</sl-radio>
<sl-radio value="2">Option 2</sl-radio>
<sl-radio value="3">Option 3</sl-radio>
</sl-radio-group>
```
```jsx:react
import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="3">
<SlRadio value="1">Option 1</SlRadio>
<SlRadio value="2">Option 2</SlRadio>
<SlRadio value="3">Option 3</SlRadio>
</SlRadioGroup>
);
```
### Disabled
Use the `disabled` attribute to disable a radio.
```html:preview
<sl-radio-group label="Select an option" name="a" value="1">
<sl-radio value="1">Option 1</sl-radio>
<sl-radio value="2" disabled>Option 2</sl-radio>
<sl-radio value="3">Option 3</sl-radio>
</sl-radio-group>
```
```jsx:react
import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRadioGroup label="Select an option" name="a" value="1">
<SlRadio value="1">Option 1</SlRadio>
<SlRadio value="2" disabled>
Option 2
</SlRadio>
<SlRadio value="3">Option 3</SlRadio>
</SlRadioGroup>
);
```
## Sizes
Add the `size` attribute to the [Radio Group](/components/radio-group) to change the radios' size.
```html preview
<sl-radio-group size="small" value="1">
<sl-radio value="1">Small 1</sl-radio>
<sl-radio value="2">Small 2</sl-radio>
<sl-radio value="3">Small 3</sl-radio>
</sl-radio-group>
<br />
<sl-radio-group size="medium" value="1">
<sl-radio value="1">Medium 1</sl-radio>
<sl-radio value="2">Medium 2</sl-radio>
<sl-radio value="3">Medium 3</sl-radio>
</sl-radio-group>
<br />
<sl-radio-group size="large" value="1">
<sl-radio value="1">Large 1</sl-radio>
<sl-radio value="2">Large 2</sl-radio>
<sl-radio value="3">Large 3</sl-radio>
</sl-radio-group>
```
```jsx react
import { SlRadio } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlRadioGroup size="small" value="1">
<SlRadio value="1">Small 1</SlRadio>
<SlRadio value="2">Small 2</SlRadio>
<SlRadio value="3">Small 3</SlRadio>
</SlRadioGroup>
<br />
<SlRadioGroup size="medium" value="1">
<SlRadio value="1">Medium 1</SlRadio>
<SlRadio value="2">Medium 2</SlRadio>
<SlRadio value="3">Medium 3</SlRadio>
</SlRadioGroup>
<br />
<SlRadioGroup size="large" value="1">
<SlRadio value="1">Large 1</SlRadio>
<SlRadio value="2">Large 2</SlRadio>
<SlRadio value="3">Large 3</SlRadio>
</SlRadioGroup>
</>
);
```

191
docs/pages/components/range.md Normal file
View File

@@ -0,0 +1,191 @@
---
meta:
title: Range
description: Ranges allow the user to select a single value within a given range using a slider.
layout: component
---
```html:preview
<sl-range></sl-range>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange />;
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Labels
Use the `label` attribute to give the range an accessible label. For labels that contain HTML, use the `label` slot instead.
```html:preview
<sl-range label="Volume" min="0" max="100"></sl-range>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange label="Volume" min={0} max={100} />;
```
### Help Text
Add descriptive help text to a range with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
```html:preview
<sl-range label="Volume" help-text="Controls the volume of the current song." min="0" max="100"></sl-range>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange label="Volume" help-text="Controls the volume of the current song." min={0} max={100} />;
```
### Min, Max, and Step
Use the `min` and `max` attributes to set the range's minimum and maximum values, respectively. The `step` attribute determines the value's interval when increasing and decreasing.
```html:preview
<sl-range min="0" max="10" step="1"></sl-range>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange min={0} max={10} step={1} />;
```
### Disabled
Use the `disabled` attribute to disable a slider.
```html:preview
<sl-range disabled></sl-range>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange disabled />;
```
### Tooltip Placement
By default, the tooltip is shown on top. Set `tooltip` to `bottom` to show it below the slider.
```html:preview
<sl-range tooltip="bottom"></sl-range>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange tooltip="bottom" />;
```
### Disable the Tooltip
To disable the tooltip, set `tooltip` to `none`.
```html:preview
<sl-range tooltip="none"></sl-range>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange tooltip="none" />;
```
### Custom Track Colors
You can customize the active and inactive portions of the track using the `--track-color-active` and `--track-color-inactive` custom properties.
```html:preview
<sl-range
style="
--track-color-active: var(--sl-color-primary-600);
--track-color-inactive: var(--sl-color-primary-100);
"
></sl-range>
```
{% raw %}
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRange
style={{
'--track-color-active': 'var(--sl-color-primary-600)',
'--track-color-inactive': 'var(--sl-color-primary-200)'
}}
/>
);
```
{% endraw %}
### Custom Track Offset
You can customize the initial offset of the active track using the `--track-active-offset` custom property.
```html:preview
<sl-range
min="-100"
max="100"
style="
--track-color-active: var(--sl-color-primary-600);
--track-color-inactive: var(--sl-color-primary-100);
--track-active-offset: 50%;
"
></sl-range>
```
{% raw %}
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRange
min={-100}
max={100}
style={{
'--track-color-active': 'var(--sl-color-primary-600)',
'--track-color-inactive': 'var(--sl-color-primary-200)',
'--track-active-offset': '50%'
}}
/>
);
```
{% endraw %}
### Custom Tooltip Formatter
You can change the tooltip's content by setting the `tooltipFormatter` property to a function that accepts the range's value as an argument.
```html:preview
<sl-range min="0" max="100" step="1" class="range-with-custom-formatter"></sl-range>
<script>
const range = document.querySelector('.range-with-custom-formatter');
range.tooltipFormatter = value => `Total - ${value}%`;
</script>
```
```jsx:react
import { SlRange } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRange min={0} max={100} step={1} tooltipFormatter={value => `Total - ${value}%`} />;
```

256
docs/pages/components/rating.md Normal file
View File

@@ -0,0 +1,256 @@
---
meta:
title: Rating
description: Ratings give users a way to quickly view and provide feedback.
layout: component
---
```html:preview
<sl-rating label="Rating"></sl-rating>
```
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRating label="Rating" />;
```
## Examples
### Labels
Ratings are commonly identified contextually, so labels aren't displayed. However, you should always provide one for assistive devices using the `label` attribute.
```html:preview
<sl-rating label="Rate this component"></sl-rating>
```
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRating label="Rate this component" />;
```
### Maximum Value
Ratings are 0-5 by default. To change the maximum possible value, use the `max` attribute.
```html:preview
<sl-rating label="Rating" max="3"></sl-rating>
```
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRating label="Rating" max={3} />;
```
### Precision
Use the `precision` attribute to let users select fractional ratings.
```html:preview
<sl-rating label="Rating" precision="0.5" value="2.5"></sl-rating>
```
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRating label="Rating" precision={0.5} value={2.5} />;
```
### Symbol Sizes
Set the `--symbol-size` custom property to adjust the size.
```html:preview
<sl-rating label="Rating" style="--symbol-size: 2rem;"></sl-rating>
```
{% raw %}
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRating label="Rating" style={{ '--symbol-size': '2rem' }} />;
```
{% endraw %}
### Readonly
Use the `readonly` attribute to display a rating that users can't change.
```html:preview
<sl-rating label="Rating" readonly value="3"></sl-rating>
```
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRating label="Rating" readonly value={3} />;
```
### Disabled
Use the `disable` attribute to disable the rating.
```html:preview
<sl-rating label="Rating" disabled value="3"></sl-rating>
```
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRating label="Rating" disabled value={3} />;
```
### Detecting Hover
Use the `sl-hover` event to detect when the user hovers over (or touch and drag) the rating. This lets you hook into values as the user interacts with the rating, but before they select a value.
The event has a payload with `phase` and `value` properties. The `phase` property tells when hovering starts, moves to a new value, and ends. The `value` property tells what the rating's value would be if the user were to commit to the hovered value.
```html:preview
<div class="detect-hover">
<sl-rating label="Rating"></sl-rating>
<span></span>
</div>
<script>
const rating = document.querySelector('.detect-hover > sl-rating');
const span = rating.nextElementSibling;
const terms = ['No rating', 'Terrible', 'Bad', 'OK', 'Good', 'Excellent'];
rating.addEventListener('sl-hover', event => {
span.textContent = terms[event.detail.value];
// Clear feedback when hovering stops
if (event.detail.phase === 'end') {
span.textContent = '';
}
});
</script>
<style>
.detect-hover span {
position: relative;
top: -4px;
left: 8px;
border-radius: var(--sl-border-radius-small);
background: var(--sl-color-neutral-900);
color: var(--sl-color-neutral-0);
text-align: center;
padding: 4px 6px;
}
.detect-hover span:empty {
display: none;
}
</style>
```
```jsx:react
import { useState } from 'react';
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const terms = ['No rating', 'Terrible', 'Bad', 'OK', 'Good', 'Excellent'];
const css = `
.detect-hover span {
position: relative;
top: -4px;
left: 8px;
border-radius: var(--sl-border-radius-small);
background: var(--sl-color-neutral-900);
color: var(--sl-color-neutral-0);
text-align: center;
padding: 4px 6px;
}
.detect-hover span:empty {
display: none;
}
`;
function handleHover(event) {
rating.addEventListener('sl-hover', event => {
setFeedback(terms[event.detail.value]);
// Clear feedback when hovering stops
if (event.detail.phase === 'end') {
setFeedback('');
}
});
}
const App = () => {
const [feedback, setFeedback] = useState(true);
return (
<>
<div class="detect-hover">
<SlRating label="Rating" onSlHover={handleHover} />
<span>{feedback}</span>
</div>
<style>{css}</style>
</>
);
};
```
### Custom Icons
You can provide custom icons by passing a function to the `getSymbol` property.
```html:preview
<sl-rating label="Rating" class="rating-hearts" style="--symbol-color-active: #ff4136;"></sl-rating>
<script>
const rating = document.querySelector('.rating-hearts');
rating.getSymbol = () => '<sl-icon name="heart-fill"></sl-icon>';
</script>
```
{% raw %}
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlRating
label="Rating"
getSymbol={() => '<sl-icon name="heart-fill"></sl-icon>'}
style={{ '--symbol-color-active': '#ff4136' }}
/>
);
```
{% endraw %}
### Value-based Icons
You can also use the `getSymbol` property to render different icons based on value.
```html:preview
<sl-rating label="Rating" class="rating-emojis"></sl-rating>
<script>
const rating = document.querySelector('.rating-emojis');
rating.getSymbol = value => {
const icons = ['emoji-angry', 'emoji-frown', 'emoji-expressionless', 'emoji-smile', 'emoji-laughing'];
return `<sl-icon name="${icons[value - 1]}"></sl-icon>`;
};
</script>
```
```jsx:react
import { SlRating } from '@shoelace-style/shoelace/dist/react';
function getSymbol(value) {
const icons = ['emoji-angry', 'emoji-frown', 'emoji-expressionless', 'emoji-smile', 'emoji-laughing'];
return `<sl-icon name="${icons[value - 1]}"></sl-icon>`;
}
const App = () => <SlRating label="Rating" getSymbol={getSymbol} />;
```

106
docs/pages/components/relative-time.md Normal file
View File

@@ -0,0 +1,106 @@
---
meta:
title: Relative Time
description: Outputs a localized time phrase relative to the current date and time.
layout: component
---
Localization is handled by the browser's [`Intl.RelativeTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). No language packs are required.
```html:preview
<!-- Shoelace 2 release date 🎉 -->
<sl-relative-time date="2020-07-15T09:17:00-04:00"></sl-relative-time>
```
```jsx:react
import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlRelativeTime date="2020-07-15T09:17:00-04:00" />;
```
The `date` attribute determines when the date/time is calculated from. It must be a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object set via JavaScript.
:::tip
When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
:::
## Examples
### Keeping Time in Sync
Use the `sync` attribute to update the displayed value automatically as time passes.
```html:preview
<div class="relative-time-sync">
<sl-relative-time sync></sl-relative-time>
</div>
<script>
const container = document.querySelector('.relative-time-sync');
const relativeTime = container.querySelector('sl-relative-time');
relativeTime.date = new Date(new Date().getTime() - 60000);
</script>
```
```jsx:react
import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
const date = new Date(new Date().getTime() - 60000);
const App = () => <SlRelativeTime date={date} sync />;
```
### Formatting Styles
You can change how the time is displayed using the `format` attribute. Note that some locales may display the same values for `narrow` and `short` formats.
```html:preview
<sl-relative-time date="2020-07-15T09:17:00-04:00" format="narrow"></sl-relative-time><br />
<sl-relative-time date="2020-07-15T09:17:00-04:00" format="short"></sl-relative-time><br />
<sl-relative-time date="2020-07-15T09:17:00-04:00" format="long"></sl-relative-time>
```
```jsx:react
import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlRelativeTime date="2020-07-15T09:17:00-04:00" format="narrow" />
<br />
<SlRelativeTime date="2020-07-15T09:17:00-04:00" format="short" />
<br />
<SlRelativeTime date="2020-07-15T09:17:00-04:00" format="long" />
</>
);
```
### Localization
Use the `lang` attribute to set the desired locale.
```html:preview
English: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="en-US"></sl-relative-time><br />
Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="zh-CN"></sl-relative-time><br />
German: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="de"></sl-relative-time><br />
Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="el"></sl-relative-time><br />
Russian: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="ru"></sl-relative-time>
```
```jsx:react
import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
English: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="en-US" />
<br />
Chinese: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="zh-CN" />
<br />
German: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="de" />
<br />
Greek: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="el" />
<br />
Russian: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="ru" />
</>
);
```

63
docs/pages/components/resize-observer.md Normal file
View File

@@ -0,0 +1,63 @@
---
meta:
title: Resize Observer
description: The Resize Observer component offers a thin, declarative interface to the ResizeObserver API.
layout: component
---
The resize observer will report changes to the dimensions of the elements it wraps through the `sl-resize` event. When emitted, a collection of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects will be attached to `event.detail` that contains the target element and information about its dimensions.
```html:preview
<div class="resize-observer-overview">
<sl-resize-observer>
<div>Resize this box and watch the console 👉</div>
</sl-resize-observer>
</div>
<script>
const container = document.querySelector('.resize-observer-overview');
const resizeObserver = container.querySelector('sl-resize-observer');
resizeObserver.addEventListener('sl-resize', event => {
console.log(event.detail);
});
</script>
<style>
.resize-observer-overview div {
display: flex;
border: solid 2px var(--sl-input-border-color);
align-items: center;
justify-content: center;
text-align: center;
padding: 4rem 2rem;
}
</style>
```
```jsx:react
import { SlResizeObserver } from '@shoelace-style/shoelace/dist/react';
const css = `
.resize-observer-overview div {
display: flex;
border: solid 2px var(--sl-input-border-color);
align-items: center;
justify-content: center;
text-align: center;
padding: 4rem 2rem;
}
`;
const App = () => (
<>
<div className="resize-observer-overview">
<SlResizeObserver onSlResize={event => console.log(event.detail)}>
<div>Resize this box and watch the console 👉</div>
</SlResizeObserver>
</div>
<style>{css}</style>
</>
);
```

439
docs/pages/components/select.md Normal file
View File

@@ -0,0 +1,439 @@
---
meta:
title: Select
description: Selects allow you to choose items from a menu of predefined options.
layout: component
---
```html:preview
<sl-select>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
<sl-option value="option-4">Option 4</sl-option>
<sl-option value="option-5">Option 5</sl-option>
<sl-option value="option-6">Option 6</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
<SlOption value="option-4">Option 4</SlOption>
<SlOption value="option-5">Option 5</SlOption>
<SlOption value="option-6">Option 6</SlOption>
</SlSelect>
);
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Labels
Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead.
```html:preview
<sl-select label="Select one">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect label="Select one">
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Help Text
Add descriptive help text to a select with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
```html:preview
<sl-select label="Experience" help-text="Please tell us your skill level.">
<sl-option value="1">Novice</sl-option>
<sl-option value="2">Intermediate</sl-option>
<sl-option value="3">Advanced</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect label="Experience" help-text="Please tell us your skill level.">
<SlOption value="1">Novice</SlOption>
<SlOption value="2">Intermediate</SlOption>
<SlOption value="3">Advanced</SlOption>
</SlSelect>
);
```
### Placeholders
Use the `placeholder` attribute to add a placeholder.
```html:preview
<sl-select placeholder="Select one">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect placeholder="Select one">
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Clearable
Use the `clearable` attribute to make the control clearable. The clear button only appears when an option is selected.
```html:preview
<sl-select clearable value="option-1">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect placeholder="Clearable" clearable>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Filled Selects
Add the `filled` attribute to draw a filled select.
```html:preview
<sl-select filled>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect filled>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Pill
Use the `pill` attribute to give selects rounded edges.
```html:preview
<sl-select pill>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect pill>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Disabled
Use the `disabled` attribute to disable a select.
```html:preview
<sl-select placeholder="Disabled" disabled>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect placeholder="Disabled" disabled>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Multiple
To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. To set multiple values at once, set `value` to a space-delimited list of values.
```html:preview
<sl-select label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
<sl-option value="option-4">Option 4</sl-option>
<sl-option value="option-5">Option 5</sl-option>
<sl-option value="option-6">Option 6</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
<SlOption value="option-4">Option 4</SlOption>
<SlOption value="option-5">Option 5</SlOption>
<SlOption value="option-6">Option 6</SlOption>
</SlSelect>
);
```
:::tip
Note that multi-select options may wrap, causing the control to expand vertically. You can use the `max-options-visible` attribute to control the maximum number of selected options to show at once.
:::
### Setting Initial Values
Use the `value` attribute to set the initial selection. When using `multiple`, use space-delimited values to select more than one option.
```html:preview
<sl-select value="option-1 option-2" multiple clearable>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
<sl-option value="option-4">Option 4</sl-option>
</sl-select>
```
```jsx:react
import { SlDivider, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect value="option-1 option-2" multiple clearable>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
);
```
### Grouping Options
Use `<sl-divider>` to group listbox items visually. You can also use `<small>` to provide labels, but they won't be announced by most assistive devices.
```html:preview
<sl-select>
<small>Section 1</small>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
<sl-divider></sl-divider>
<small>Section 2</small>
<sl-option value="option-4">Option 4</sl-option>
<sl-option value="option-5">Option 5</sl-option>
<sl-option value="option-6">Option 6</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
<SlOption value="option-4">Option 4</SlOption>
<SlOption value="option-5">Option 5</SlOption>
<SlOption value="option-6">Option 6</SlOption>
</SlSelect>
);
```
### Sizes
Use the `size` attribute to change a select's size. Note that size does not apply to listbox options.
```html:preview
<sl-select placeholder="Small" size="small">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
<br />
<sl-select placeholder="Medium" size="medium">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
<br />
<sl-select placeholder="Large" size="large">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlSelect placeholder="Small" size="small">
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
<br />
<SlSelect placeholder="Medium" size="medium">
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
<br />
<SlSelect placeholder="Large" size="large">
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
</>
);
```
### Placement
The preferred placement of the select's listbox can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are `top` and `bottom`.
```html:preview
<sl-select placement="top">
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import {
SlOption,
SlSelect
} from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSelect placement="top">
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlDropdown>
);
```
### Prefix Icons
Use the `prefix` slot to prepend an icon to the control.
```html:preview
<sl-select placeholder="Small" size="small" clearable>
<sl-icon name="house" slot="prefix"></sl-icon>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
<br />
<sl-select placeholder="Medium" size="medium" clearable>
<sl-icon name="house" slot="prefix"></sl-icon>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
<br />
<sl-select placeholder="Large" size="large" clearable>
<sl-icon name="house" slot="prefix"></sl-icon>
<sl-option value="option-1">Option 1</sl-option>
<sl-option value="option-2">Option 2</sl-option>
<sl-option value="option-3">Option 3</sl-option>
</sl-select>
```
```jsx:react
import { SlIcon, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlSelect placeholder="Small" size="small">
<SlIcon name="house" slot="prefix"></SlIcon>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
<br />
<SlSelect placeholder="Medium" size="medium">
<SlIcon name="house" slot="prefix"></SlIcon>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
<br />
<SlSelect placeholder="Large" size="large">
<SlIcon name="house" slot="prefix"></SlIcon>
<SlOption value="option-1">Option 1</SlOption>
<SlOption value="option-2">Option 2</SlOption>
<SlOption value="option-3">Option 3</SlOption>
</SlSelect>
</>
);
```

448
docs/pages/components/skeleton.md Normal file
View File

@@ -0,0 +1,448 @@
---
meta:
title: Skeleton
description: Skeletons are used to provide a visual representation of where content will eventually be drawn.
layout: component
---
These are simple containers for scaffolding layouts that mimic what users will see when content has finished loading. This prevents large areas of empty space during asynchronous operations.
Skeletons try not to be opinionated, as there are endless possibilities for designing layouts. Therefore, you'll likely use more than one skeleton to create the effect you want. If you find yourself using them frequently, consider creating a template that renders them with the desired arrangement and styles.
```html:preview
<div class="skeleton-overview">
<header>
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
</header>
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
</div>
<style>
.skeleton-overview header {
display: flex;
align-items: center;
margin-bottom: 1rem;
}
.skeleton-overview header sl-skeleton:last-child {
flex: 0 0 auto;
width: 30%;
}
.skeleton-overview sl-skeleton {
margin-bottom: 1rem;
}
.skeleton-overview sl-skeleton:nth-child(1) {
float: left;
width: 3rem;
height: 3rem;
margin-right: 1rem;
vertical-align: middle;
}
.skeleton-overview sl-skeleton:nth-child(3) {
width: 95%;
}
.skeleton-overview sl-skeleton:nth-child(4) {
width: 80%;
}
</style>
```
```jsx:react
import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
const css = `
.skeleton-overview header {
display: flex;
align-items: center;
margin-bottom: 1rem;
}
.skeleton-overview header sl-skeleton:last-child {
flex: 0 0 auto;
width: 30%;
}
.skeleton-overview sl-skeleton {
margin-bottom: 1rem;
}
.skeleton-overview sl-skeleton:nth-child(1) {
float: left;
width: 3rem;
height: 3rem;
margin-right: 1rem;
vertical-align: middle;
}
.skeleton-overview sl-skeleton:nth-child(3) {
width: 95%;
}
.skeleton-overview sl-skeleton:nth-child(4) {
width: 80%;
}
`;
const App = () => (
<>
<div className="skeleton-overview">
<header>
<SlSkeleton />
<SlSkeleton />
</header>
<SlSkeleton />
<SlSkeleton />
<SlSkeleton />
</div>
<style>{css}</style>
</>
);
```
## Examples
### Effects
There are two built-in effects, `sheen` and `pulse`. Effects are intentionally subtle, as they can be distracting when used extensively. The default is `none`, which displays a static, non-animated skeleton.
```html:preview
<div class="skeleton-effects">
<sl-skeleton effect="none"></sl-skeleton>
None
<sl-skeleton effect="sheen"></sl-skeleton>
Sheen
<sl-skeleton effect="pulse"></sl-skeleton>
Pulse
</div>
<style>
.skeleton-effects {
font-size: var(--sl-font-size-small);
}
.skeleton-effects sl-skeleton:not(:first-child) {
margin-top: 1rem;
}
</style>
```
```jsx:react
import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
const css = `
.skeleton-effects {
font-size: var(--sl-font-size-small);
}
.skeleton-effects sl-skeleton:not(:first-child) {
margin-top: 1rem;
}
`;
const App = () => (
<>
<div className="skeleton-effects">
<SlSkeleton effect="none" />
None
<SlSkeleton effect="sheen" />
Sheen
<SlSkeleton effect="pulse" />
Pulse
</div>
<style>{css}</style>
</>
);
```
### Paragraphs
Use multiple skeletons and some clever styles to simulate paragraphs.
```html:preview
<div class="skeleton-paragraphs">
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
</div>
<style>
.skeleton-paragraphs sl-skeleton {
margin-bottom: 1rem;
}
.skeleton-paragraphs sl-skeleton:nth-child(2) {
width: 95%;
}
.skeleton-paragraphs sl-skeleton:nth-child(4) {
width: 90%;
}
.skeleton-paragraphs sl-skeleton:last-child {
width: 50%;
}
</style>
```
```jsx:react
import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
const css = `
.skeleton-paragraphs sl-skeleton {
margin-bottom: 1rem;
}
.skeleton-paragraphs sl-skeleton:nth-child(2) {
width: 95%;
}
.skeleton-paragraphs sl-skeleton:nth-child(4) {
width: 90%;
}
.skeleton-paragraphs sl-skeleton:last-child {
width: 50%;
}
`;
const App = () => (
<>
<div className="skeleton-paragraphs">
<SlSkeleton />
<SlSkeleton />
<SlSkeleton />
<SlSkeleton />
<SlSkeleton />
</div>
<style>{css}</style>
</>
);
```
### Avatars
Set a matching width and height to make a circle, square, or rounded avatar skeleton.
```html:preview
<div class="skeleton-avatars">
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
<sl-skeleton></sl-skeleton>
</div>
<style>
.skeleton-avatars sl-skeleton {
display: inline-block;
width: 3rem;
height: 3rem;
margin-right: 0.5rem;
}
.skeleton-avatars sl-skeleton:nth-child(1) {
--border-radius: 0;
}
.skeleton-avatars sl-skeleton:nth-child(2) {
--border-radius: var(--sl-border-radius-medium);
}
</style>
```
```jsx:react
import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
const css = `
.skeleton-avatars sl-skeleton {
display: inline-block;
width: 3rem;
height: 3rem;
margin-right: .5rem;
}
.skeleton-avatars sl-skeleton:nth-child(1) {
--border-radius: 0;
}
.skeleton-avatars sl-skeleton:nth-child(2) {
--border-radius: var(--sl-border-radius-medium);
}
`;
const App = () => (
<>
<div className="skeleton-avatars">
<SlSkeleton />
<SlSkeleton />
<SlSkeleton />
</div>
<style>{css}</style>
</>
);
```
### Custom Shapes
Use the `--border-radius` custom property to make circles, squares, and rectangles. For more complex shapes, you can apply `clip-path` to the `indicator` part. [Try Clippy](https://bennettfeely.com/clippy/) if you need help generating custom shapes.
```html:preview
<div class="skeleton-shapes">
<sl-skeleton class="square"></sl-skeleton>
<sl-skeleton class="circle"></sl-skeleton>
<sl-skeleton class="triangle"></sl-skeleton>
<sl-skeleton class="cross"></sl-skeleton>
<sl-skeleton class="comment"></sl-skeleton>
</div>
<style>
.skeleton-shapes sl-skeleton {
display: inline-flex;
width: 50px;
height: 50px;
}
.skeleton-shapes .square::part(indicator) {
--border-radius: var(--sl-border-radius-medium);
}
.skeleton-shapes .circle::part(indicator) {
--border-radius: var(--sl-border-radius-circle);
}
.skeleton-shapes .triangle::part(indicator) {
--border-radius: 0;
clip-path: polygon(50% 0, 0 100%, 100% 100%);
}
.skeleton-shapes .cross::part(indicator) {
--border-radius: 0;
clip-path: polygon(
20% 0%,
0% 20%,
30% 50%,
0% 80%,
20% 100%,
50% 70%,
80% 100%,
100% 80%,
70% 50%,
100% 20%,
80% 0%,
50% 30%
);
}
.skeleton-shapes .comment::part(indicator) {
--border-radius: 0;
clip-path: polygon(0% 0%, 100% 0%, 100% 75%, 75% 75%, 75% 100%, 50% 75%, 0% 75%);
}
.skeleton-shapes sl-skeleton:not(:last-child) {
margin-right: 0.5rem;
}
</style>
```
```jsx:react
import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
const css = `
.skeleton-shapes sl-skeleton {
display: inline-flex;
width: 50px;
height: 50px;
}
.skeleton-shapes .square::part(indicator) {
--border-radius: var(--sl-border-radius-medium);
}
.skeleton-shapes .circle::part(indicator) {
--border-radius: var(--sl-border-radius-circle);
}
.skeleton-shapes .triangle::part(indicator) {
--border-radius: 0;
clip-path: polygon(50% 0, 0 100%, 100% 100%);
}
.skeleton-shapes .cross::part(indicator) {
--border-radius: 0;
clip-path: polygon(20% 0%, 0% 20%, 30% 50%, 0% 80%, 20% 100%, 50% 70%, 80% 100%, 100% 80%, 70% 50%, 100% 20%, 80% 0%, 50% 30%);
}
.skeleton-shapes .comment::part(indicator) {
--border-radius: 0;
clip-path: polygon(0% 0%, 100% 0%, 100% 75%, 75% 75%, 75% 100%, 50% 75%, 0% 75%);
}
.skeleton-shapes sl-skeleton:not(:last-child) {
margin-right: .5rem;
}
`;
const App = () => (
<>
<div className="skeleton-shapes">
<SlSkeleton className="square" />
<SlSkeleton className="circle" />
<SlSkeleton className="triangle" />
<SlSkeleton className="cross" />
<SlSkeleton className="comment" />
</div>
<style>{css}</style>
</>
);
```
### Custom Colors
Set the `--color` and `--sheen-color` custom properties to adjust the skeleton's color.
```html:preview
<sl-skeleton effect="sheen" style="--color: tomato; --sheen-color: #ffb094;"></sl-skeleton>
```
{% raw %}
```jsx:react
import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
const css = `
.skeleton-avatars sl-skeleton {
display: inline-block;
width: 3rem;
height: 3rem;
margin-right: .5rem;
}
.skeleton-avatars sl-skeleton:nth-child(1) {
--border-radius: 0;
}
.skeleton-avatars sl-skeleton:nth-child(2) {
--border-radius: var(--sl-border-radius-medium);
}
`;
const App = () => <SlSkeleton effect="sheen" style={{ '--color': 'tomato', '--sheen-color': '#ffb094' }} />;
```
{% endraw %}

95
docs/pages/components/spinner.md Normal file
View File

@@ -0,0 +1,95 @@
---
meta:
title: Spinner
description: Spinners are used to show the progress of an indeterminate operation.
layout: component
---
```html:preview
<sl-spinner></sl-spinner>
```
```jsx:react
import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlSpinner />;
```
## Examples
### Size
Spinners are sized based on the current font size. To change their size, set the `font-size` property on the spinner itself or on a parent element as shown below.
```html:preview
<sl-spinner></sl-spinner>
<sl-spinner style="font-size: 2rem;"></sl-spinner>
<sl-spinner style="font-size: 3rem;"></sl-spinner>
```
{% raw %}
```jsx:react
import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlSpinner />
<SlSpinner style={{ fontSize: '2rem' }} />
<SlSpinner style={{ fontSize: '3rem' }} />
</>
);
```
{% endraw %}
### Track Width
The width of the spinner's track can be changed by setting the `--track-width` custom property.
```html:preview
<sl-spinner style="font-size: 50px; --track-width: 10px;"></sl-spinner>
```
{% raw %}
```jsx:react
import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSpinner
style={{
fontSize: '3rem',
'--track-width': '6px'
}}
/>
);
```
{% endraw %}
### Color
The spinner's colors can be changed by setting the `--indicator-color` and `--track-color` custom properties.
```html:preview
<sl-spinner style="font-size: 3rem; --indicator-color: deeppink; --track-color: pink;"></sl-spinner>
```
{% raw %}
```jsx:react
import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSpinner
style={{
fontSize: '3rem',
'--indicator-color': 'deeppink',
'--track-color': 'pink'
}}
/>
);
```
{% endraw %}

797
docs/pages/components/split-panel.md Normal file
View File

@@ -0,0 +1,797 @@
---
meta:
title: Split Panel
description: Split panels display two adjacent panels, allowing the user to reposition them.
layout: component
---
```html:preview
<sl-split-panel>
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
```
{% raw %}
```jsx:react
import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSplitPanel>
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
);
```
{% endraw %}
## Examples
### Initial Position
To set the initial position, use the `position` attribute. If no position is provided, it will default to 50% of the available space.
```html:preview
<sl-split-panel position="75">
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
```
### Initial Position in Pixels
To set the initial position in pixels instead of a percentage, use the `position-in-pixels` attribute.
```html:preview
<sl-split-panel position-in-pixels="150">
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
```
{% raw %}
```jsx:react
import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSplitPanel position="200">
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
);
```
{% endraw %}
### Vertical
Add the `vertical` attribute to render the split panel in a vertical orientation where the start and end panels are stacked. You also need to set a height when using the vertical orientation.
```html:preview
<sl-split-panel vertical style="height: 400px;">
<div
slot="start"
style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
```
{% raw %}
```jsx:react
import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSplitPanel vertical style={{ height: '400px' }}>
<div
slot="start"
style={{
height: '100%',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '100%',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
);
```
{% endraw %}
### Snapping
To snap panels at specific positions while dragging, add the `snap` attribute with one or more space-separated values. Values must be in pixels or percentages. For example, to snap the panel at `100px` and `50%`, use `snap="100px 50%"`. You can also customize how close the divider must be before snapping with the `snap-threshold` attribute.
```html:preview
<div class="split-panel-snapping">
<sl-split-panel snap="100px 50%">
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
<div class="split-panel-snapping-dots"></div>
</div>
<style>
.split-panel-snapping {
position: relative;
}
.split-panel-snapping-dots::before,
.split-panel-snapping-dots::after {
content: '';
position: absolute;
bottom: -12px;
width: 6px;
height: 6px;
border-radius: 50%;
background: var(--sl-color-neutral-400);
transform: translateX(-3px);
}
.split-panel-snapping-dots::before {
left: 100px;
}
.split-panel-snapping-dots::after {
left: 50%;
}
</style>
```
{% raw %}
```jsx:react
import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
const css = `
.split-panel-snapping {
position: relative;
}
.split-panel-snapping-dots::before,
.split-panel-snapping-dots::after {
content: '';
position: absolute;
bottom: -12px;
width: 6px;
height: 6px;
border-radius: 50%;
background: var(--sl-color-neutral-400);
transform: translateX(-3px);
}
.split-panel-snapping-dots::before {
left: 100px;
}
.split-panel-snapping-dots::after {
left: 50%;
}
`;
const App = () => (
<>
<div className="split-panel-snapping">
<SlSplitPanel snap="100px 50%">
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
<div className="split-panel-snapping-dots" />
</div>
<style>{css}</style>
</>
);
```
{% endraw %}
### Disabled
Add the `disabled` attribute to prevent the divider from being repositioned.
```html:preview
<sl-split-panel disabled>
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
```
{% raw %}
```jsx:react
import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSplitPanel disabled>
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
);
```
{% endraw %}
### Setting the Primary Panel
By default, both panels will grow or shrink proportionally when the host element is resized. If a primary panel is designated, it will maintain its size and the secondary panel will grow or shrink to fit the remaining space. You can set the primary panel to `start` or `end` using the `primary` attribute.
Try resizing the example below with each option and notice how the panels respond.
```html:preview
<div class="split-panel-primary">
<sl-split-panel>
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
<sl-select label="Primary Panel" value="" style="max-width: 200px; margin-top: 1rem;">
<sl-option value="">None</sl-option>
<sl-option value="start">Start</sl-option>
<sl-option value="end">End</sl-option>
</sl-select>
</div>
<script>
const container = document.querySelector('.split-panel-primary');
const splitPanel = container.querySelector('sl-split-panel');
const select = container.querySelector('sl-select');
select.addEventListener('sl-change', () => (splitPanel.primary = select.value));
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlSplitPanel, SlSelect, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [primary, setPrimary] = useState('');
return (
<>
<SlSplitPanel primary={primary}>
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
<SlSelect
label="Primary Panel"
value={primary}
style={{ maxWidth: '200px', marginTop: '1rem' }}
onSlChange={event => setPrimary(event.target.value)}
>
<SlMenuItem value="">None</SlMenuItem>
<SlMenuItem value="start">Start</SlMenuItem>
<SlMenuItem value="end">End</SlMenuItem>
</SlSelect>
</>
);
};
```
{% endraw %}
### Min & Max
To set a minimum or maximum size of the primary panel, use the `--min` and `--max` custom properties. Since the secondary panel is flexible, size constraints can only be applied to the primary panel. If no primary panel is designated, these constraints will be applied to the `start` panel.
This examples demonstrates how you can ensure both panels are at least 150px using `--min`, `--max`, and the `calc()` function.
```html:preview
<sl-split-panel style="--min: 150px; --max: calc(100% - 150px);">
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
```
{% raw %}
```jsx:react
import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSplitPanel style={{ '--min': '150px', '--max': 'calc(100% - 150px)' }}>
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
);
```
{% endraw %}
### Nested Split Panels
Create complex layouts that can be repositioned independently by nesting split panels.
```html:preview
<sl-split-panel>
<div
slot="start"
style="height: 400px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div slot="end">
<sl-split-panel vertical style="height: 400px;">
<div
slot="start"
style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Top
</div>
<div
slot="end"
style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Bottom
</div>
</sl-split-panel>
</div>
</sl-split-panel>
```
{% raw %}
```jsx:react
import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSplitPanel>
<div
slot="start"
style={{
height: '400px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div slot="end">
<SlSplitPanel vertical style={{ height: '400px' }}>
<div
slot="start"
style={{
height: '100%',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '100%',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
</div>
</SlSplitPanel>
);
```
{% endraw %}
### Customizing the Divider
You can target the `divider` part to apply CSS properties to the divider. To add a custom handle, slot an icon into the `divider` slot. When customizing the divider, make sure to think about focus styles for keyboard users.
```html:preview
<sl-split-panel style="--divider-width: 20px;">
<sl-icon slot="divider" name="grip-vertical"></sl-icon>
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
```
{% raw %}
```jsx:react
import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSplitPanel style={{ '--divider-width': '20px' }}>
<SlIcon slot="divider" name="grip-vertical" />
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
);
```
{% endraw %}
Here's a more elaborate example that changes the divider's color and width and adds a styled handle.
```html:preview
<div class="split-panel-divider">
<sl-split-panel>
<sl-icon slot="divider" name="grip-vertical"></sl-icon>
<div
slot="start"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
Start
</div>
<div
slot="end"
style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
>
End
</div>
</sl-split-panel>
</div>
<style>
.split-panel-divider sl-split-panel {
--divider-width: 2px;
}
.split-panel-divider sl-split-panel::part(divider) {
background-color: var(--sl-color-pink-600);
}
.split-panel-divider sl-icon {
position: absolute;
border-radius: var(--sl-border-radius-small);
background: var(--sl-color-pink-600);
color: var(--sl-color-neutral-0);
padding: 0.5rem 0.125rem;
}
.split-panel-divider sl-split-panel::part(divider):focus-visible {
background-color: var(--sl-color-primary-600);
}
.split-panel-divider sl-split-panel:focus-within sl-icon {
background-color: var(--sl-color-primary-600);
color: var(--sl-color-neutral-0);
}
</style>
```
{% raw %}
```jsx:react
import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
const css = `
.split-panel-divider sl-split-panel {
--divider-width: 2px;
}
.split-panel-divider sl-split-panel::part(divider) {
background-color: var(--sl-color-pink-600);
}
.split-panel-divider sl-icon {
position: absolute;
border-radius: var(--sl-border-radius-small);
background: var(--sl-color-pink-600);
color: var(--sl-color-neutral-0);
padding: .5rem .125rem;
}
.split-panel-divider sl-split-panel::part(divider):focus-visible {
background-color: var(--sl-color-primary-600);
}
.split-panel-divider sl-split-panel:focus-within sl-icon {
background-color: var(--sl-color-primary-600);
color: var(--sl-color-neutral-0);
}
`;
const App = () => (
<>
<div className="split-panel-divider">
<SlSplitPanel>
<SlIcon slot="divider" name="grip-vertical" />
<div
slot="start"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
Start
</div>
<div
slot="end"
style={{
height: '200px',
background: 'var(--sl-color-neutral-50)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center'
}}
>
End
</div>
</SlSplitPanel>
</div>
<style>{css}</style>
</>
);
```
{% endraw %}

102
docs/pages/components/switch.md Normal file
View File

@@ -0,0 +1,102 @@
---
meta:
title: Switch
description: Switches allow the user to toggle an option on or off.
layout: component
---
```html:preview
<sl-switch>Switch</sl-switch>
```
```jsx:react
import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlSwitch>Switch</SlSwitch>;
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Checked
Use the `checked` attribute to activate the switch.
```html:preview
<sl-switch checked>Checked</sl-switch>
```
```jsx:react
import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlSwitch checked>Checked</SlSwitch>;
```
### Disabled
Use the `disabled` attribute to disable the switch.
```html:preview
<sl-switch disabled>Disabled</sl-switch>
```
```jsx:react
import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlSwitch disabled>Disabled</SlSwitch>;
```
### Sizes
Use the `size` attribute to change a switch's size.
```html:preview
<sl-switch size="small">Small</sl-switch>
<br />
<sl-switch size="medium">Medium</sl-switch>
<br />
<sl-switch size="large">Large</sl-switch>
```
```jsx:react
import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlSwitch size="small">Small</SlSwitch>
<br />
<SlSwitch size="medium">Medium</SlSwitch>
<br />
<SlSwitch size="large">Large</SlSwitch>
</>
);
```
### Custom Styles
Use the available custom properties to change how the switch is styled.
```html:preview
<sl-switch style="--width: 80px; --height: 40px; --thumb-size: 36px;">Really big</sl-switch>
```
{% raw %}
```jsx:react
import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlSwitch
style={{
'--width': '80px',
'--height': '32px',
'--thumb-size': '26px'
}}
/>
);
```
{% endraw %}

444
docs/pages/components/tab-group.md Normal file
View File

@@ -0,0 +1,444 @@
---
meta:
title: Tab Group
description: Tab groups organize content into a container that shows one section at a time.
layout: component
---
Tab groups make use of [tabs](/components/tab) and [tab panels](/components/tab-panel). Each tab must be slotted into the `nav` slot and its `panel` must refer to a tab panel of the same name.
```html:preview
<sl-tab-group>
<sl-tab slot="nav" panel="general">General</sl-tab>
<sl-tab slot="nav" panel="custom">Custom</sl-tab>
<sl-tab slot="nav" panel="advanced">Advanced</sl-tab>
<sl-tab slot="nav" panel="disabled" disabled>Disabled</sl-tab>
<sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
<sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
<sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
<sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTabGroup>
<SlTab slot="nav" panel="general">
General
</SlTab>
<SlTab slot="nav" panel="custom">
Custom
</SlTab>
<SlTab slot="nav" panel="advanced">
Advanced
</SlTab>
<SlTab slot="nav" panel="disabled" disabled>
Disabled
</SlTab>
<SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
<SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
<SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
<SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
</SlTabGroup>
);
```
## Examples
### Tabs on Bottom
Tabs can be shown on the bottom by setting `placement` to `bottom`.
```html:preview
<sl-tab-group placement="bottom">
<sl-tab slot="nav" panel="general">General</sl-tab>
<sl-tab slot="nav" panel="custom">Custom</sl-tab>
<sl-tab slot="nav" panel="advanced">Advanced</sl-tab>
<sl-tab slot="nav" panel="disabled" disabled>Disabled</sl-tab>
<sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
<sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
<sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
<sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTabGroup placement="bottom">
<SlTab slot="nav" panel="general">
General
</SlTab>
<SlTab slot="nav" panel="custom">
Custom
</SlTab>
<SlTab slot="nav" panel="advanced">
Advanced
</SlTab>
<SlTab slot="nav" panel="disabled" disabled>
Disabled
</SlTab>
<SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
<SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
<SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
<SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
</SlTabGroup>
);
```
### Tabs on Start
Tabs can be shown on the starting side by setting `placement` to `start`.
```html:preview
<sl-tab-group placement="start">
<sl-tab slot="nav" panel="general">General</sl-tab>
<sl-tab slot="nav" panel="custom">Custom</sl-tab>
<sl-tab slot="nav" panel="advanced">Advanced</sl-tab>
<sl-tab slot="nav" panel="disabled" disabled>Disabled</sl-tab>
<sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
<sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
<sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
<sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTabGroup placement="start">
<SlTab slot="nav" panel="general">
General
</SlTab>
<SlTab slot="nav" panel="custom">
Custom
</SlTab>
<SlTab slot="nav" panel="advanced">
Advanced
</SlTab>
<SlTab slot="nav" panel="disabled" disabled>
Disabled
</SlTab>
<SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
<SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
<SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
<SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
</SlTabGroup>
);
```
### Tabs on End
Tabs can be shown on the ending side by setting `placement` to `end`.
```html:preview
<sl-tab-group placement="end">
<sl-tab slot="nav" panel="general">General</sl-tab>
<sl-tab slot="nav" panel="custom">Custom</sl-tab>
<sl-tab slot="nav" panel="advanced">Advanced</sl-tab>
<sl-tab slot="nav" panel="disabled" disabled>Disabled</sl-tab>
<sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
<sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
<sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
<sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTabGroup placement="end">
<SlTab slot="nav" panel="general">
General
</SlTab>
<SlTab slot="nav" panel="custom">
Custom
</SlTab>
<SlTab slot="nav" panel="advanced">
Advanced
</SlTab>
<SlTab slot="nav" panel="disabled" disabled>
Disabled
</SlTab>
<SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
<SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
<SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
<SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
</SlTabGroup>
);
```
### Closable Tabs
Add the `closable` attribute to a tab to show a close button. This example shows how you can dynamically remove tabs from the DOM when the close button is activated.
```html:preview
<sl-tab-group class="tabs-closable">
<sl-tab slot="nav" panel="general">General</sl-tab>
<sl-tab slot="nav" panel="closable-1" closable>Closable 1</sl-tab>
<sl-tab slot="nav" panel="closable-2" closable>Closable 2</sl-tab>
<sl-tab slot="nav" panel="closable-3" closable>Closable 3</sl-tab>
<sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
<sl-tab-panel name="closable-1">This is the first closable tab panel.</sl-tab-panel>
<sl-tab-panel name="closable-2">This is the second closable tab panel.</sl-tab-panel>
<sl-tab-panel name="closable-3">This is the third closable tab panel.</sl-tab-panel>
</sl-tab-group>
<script>
const tabGroup = document.querySelector('.tabs-closable');
tabGroup.addEventListener('sl-close', async event => {
const tab = event.target;
const panel = tabGroup.querySelector(`sl-tab-panel[name="${tab.panel}"]`);
// Show the previous tab if the tab is currently active
if (tab.active) {
tabGroup.show(tab.previousElementSibling.panel);
}
// Remove the tab + panel
tab.remove();
panel.remove();
});
</script>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleClose(event) {
//
// This is a crude example that removes the tab and its panel from the DOM.
// There are better ways to manage tab creation/removal in React, but that
// would significantly complicate the example.
//
const tab = event.target;
const tabGroup = tab.closest('sl-tab-group');
const tabPanel = tabGroup.querySelector(`[aria-labelledby="${tab.id}"]`);
tab.remove();
tabPanel.remove();
}
return (
<SlTabGroup className="tabs-closable" onSlClose={handleClose}>
<SlTab slot="nav" panel="general">
General
</SlTab>
<SlTab slot="nav" panel="closable-1" closable onSlClose={handleClose}>
Closable 1
</SlTab>
<SlTab slot="nav" panel="closable-2" closable onSlClose={handleClose}>
Closable 2
</SlTab>
<SlTab slot="nav" panel="closable-3" closable onSlClose={handleClose}>
Closable 3
</SlTab>
<SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
<SlTabPanel name="closable-1">This is the first closable tab panel.</SlTabPanel>
<SlTabPanel name="closable-2">This is the second closable tab panel.</SlTabPanel>
<SlTabPanel name="closable-3">This is the third closable tab panel.</SlTabPanel>
</SlTabGroup>
);
};
```
### Scrolling Tabs
When there are more tabs than horizontal space allows, the nav will be scrollable.
```html:preview
<sl-tab-group>
<sl-tab slot="nav" panel="tab-1">Tab 1</sl-tab>
<sl-tab slot="nav" panel="tab-2">Tab 2</sl-tab>
<sl-tab slot="nav" panel="tab-3">Tab 3</sl-tab>
<sl-tab slot="nav" panel="tab-4">Tab 4</sl-tab>
<sl-tab slot="nav" panel="tab-5">Tab 5</sl-tab>
<sl-tab slot="nav" panel="tab-6">Tab 6</sl-tab>
<sl-tab slot="nav" panel="tab-7">Tab 7</sl-tab>
<sl-tab slot="nav" panel="tab-8">Tab 8</sl-tab>
<sl-tab slot="nav" panel="tab-9">Tab 9</sl-tab>
<sl-tab slot="nav" panel="tab-10">Tab 10</sl-tab>
<sl-tab slot="nav" panel="tab-11">Tab 11</sl-tab>
<sl-tab slot="nav" panel="tab-12">Tab 12</sl-tab>
<sl-tab slot="nav" panel="tab-13">Tab 13</sl-tab>
<sl-tab slot="nav" panel="tab-14">Tab 14</sl-tab>
<sl-tab slot="nav" panel="tab-15">Tab 15</sl-tab>
<sl-tab slot="nav" panel="tab-16">Tab 16</sl-tab>
<sl-tab slot="nav" panel="tab-17">Tab 17</sl-tab>
<sl-tab slot="nav" panel="tab-18">Tab 18</sl-tab>
<sl-tab slot="nav" panel="tab-19">Tab 19</sl-tab>
<sl-tab slot="nav" panel="tab-20">Tab 20</sl-tab>
<sl-tab-panel name="tab-1">Tab panel 1</sl-tab-panel>
<sl-tab-panel name="tab-2">Tab panel 2</sl-tab-panel>
<sl-tab-panel name="tab-3">Tab panel 3</sl-tab-panel>
<sl-tab-panel name="tab-4">Tab panel 4</sl-tab-panel>
<sl-tab-panel name="tab-5">Tab panel 5</sl-tab-panel>
<sl-tab-panel name="tab-6">Tab panel 6</sl-tab-panel>
<sl-tab-panel name="tab-7">Tab panel 7</sl-tab-panel>
<sl-tab-panel name="tab-8">Tab panel 8</sl-tab-panel>
<sl-tab-panel name="tab-9">Tab panel 9</sl-tab-panel>
<sl-tab-panel name="tab-10">Tab panel 10</sl-tab-panel>
<sl-tab-panel name="tab-11">Tab panel 11</sl-tab-panel>
<sl-tab-panel name="tab-12">Tab panel 12</sl-tab-panel>
<sl-tab-panel name="tab-13">Tab panel 13</sl-tab-panel>
<sl-tab-panel name="tab-14">Tab panel 14</sl-tab-panel>
<sl-tab-panel name="tab-15">Tab panel 15</sl-tab-panel>
<sl-tab-panel name="tab-16">Tab panel 16</sl-tab-panel>
<sl-tab-panel name="tab-17">Tab panel 17</sl-tab-panel>
<sl-tab-panel name="tab-18">Tab panel 18</sl-tab-panel>
<sl-tab-panel name="tab-19">Tab panel 19</sl-tab-panel>
<sl-tab-panel name="tab-20">Tab panel 20</sl-tab-panel>
</sl-tab-group>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTabGroup>
<SlTab slot="nav" panel="tab-1">
Tab 1
</SlTab>
<SlTab slot="nav" panel="tab-2">
Tab 2
</SlTab>
<SlTab slot="nav" panel="tab-3">
Tab 3
</SlTab>
<SlTab slot="nav" panel="tab-4">
Tab 4
</SlTab>
<SlTab slot="nav" panel="tab-5">
Tab 5
</SlTab>
<SlTab slot="nav" panel="tab-6">
Tab 6
</SlTab>
<SlTab slot="nav" panel="tab-7">
Tab 7
</SlTab>
<SlTab slot="nav" panel="tab-8">
Tab 8
</SlTab>
<SlTab slot="nav" panel="tab-9">
Tab 9
</SlTab>
<SlTab slot="nav" panel="tab-10">
Tab 10
</SlTab>
<SlTab slot="nav" panel="tab-11">
Tab 11
</SlTab>
<SlTab slot="nav" panel="tab-12">
Tab 12
</SlTab>
<SlTab slot="nav" panel="tab-13">
Tab 13
</SlTab>
<SlTab slot="nav" panel="tab-14">
Tab 14
</SlTab>
<SlTab slot="nav" panel="tab-15">
Tab 15
</SlTab>
<SlTab slot="nav" panel="tab-16">
Tab 16
</SlTab>
<SlTab slot="nav" panel="tab-17">
Tab 17
</SlTab>
<SlTab slot="nav" panel="tab-18">
Tab 18
</SlTab>
<SlTab slot="nav" panel="tab-19">
Tab 19
</SlTab>
<SlTab slot="nav" panel="tab-20">
Tab 20
</SlTab>
<SlTabPanel name="tab-1">Tab panel 1</SlTabPanel>
<SlTabPanel name="tab-2">Tab panel 2</SlTabPanel>
<SlTabPanel name="tab-3">Tab panel 3</SlTabPanel>
<SlTabPanel name="tab-4">Tab panel 4</SlTabPanel>
<SlTabPanel name="tab-5">Tab panel 5</SlTabPanel>
<SlTabPanel name="tab-6">Tab panel 6</SlTabPanel>
<SlTabPanel name="tab-7">Tab panel 7</SlTabPanel>
<SlTabPanel name="tab-8">Tab panel 8</SlTabPanel>
<SlTabPanel name="tab-9">Tab panel 9</SlTabPanel>
<SlTabPanel name="tab-10">Tab panel 10</SlTabPanel>
<SlTabPanel name="tab-11">Tab panel 11</SlTabPanel>
<SlTabPanel name="tab-12">Tab panel 12</SlTabPanel>
<SlTabPanel name="tab-13">Tab panel 13</SlTabPanel>
<SlTabPanel name="tab-14">Tab panel 14</SlTabPanel>
<SlTabPanel name="tab-15">Tab panel 15</SlTabPanel>
<SlTabPanel name="tab-16">Tab panel 16</SlTabPanel>
<SlTabPanel name="tab-17">Tab panel 17</SlTabPanel>
<SlTabPanel name="tab-18">Tab panel 18</SlTabPanel>
<SlTabPanel name="tab-19">Tab panel 19</SlTabPanel>
<SlTabPanel name="tab-20">Tab panel 20</SlTabPanel>
</SlTabGroup>
);
```
### Manual Activation
When focused, keyboard users can press [[Left]] or [[Right]] to select the desired tab. By default, the corresponding tab panel will be shown immediately (automatic activation). You can change this behavior by setting `activation="manual"` which will require the user to press [[Space]] or [[Enter]] before showing the tab panel (manual activation).
```html:preview
<sl-tab-group activation="manual">
<sl-tab slot="nav" panel="general">General</sl-tab>
<sl-tab slot="nav" panel="custom">Custom</sl-tab>
<sl-tab slot="nav" panel="advanced">Advanced</sl-tab>
<sl-tab slot="nav" panel="disabled" disabled>Disabled</sl-tab>
<sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
<sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
<sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
<sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTabGroup activation="manual">
<SlTab slot="nav" panel="general">
General
</SlTab>
<SlTab slot="nav" panel="custom">
Custom
</SlTab>
<SlTab slot="nav" panel="advanced">
Advanced
</SlTab>
<SlTab slot="nav" panel="disabled" disabled>
Disabled
</SlTab>
<SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
<SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
<SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
<SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
</SlTabGroup>
);
```

50
docs/pages/components/tab-panel.md Normal file
View File

@@ -0,0 +1,50 @@
---
meta:
title: Tab Panel
description: Tab panels are used inside tab groups to display tabbed content.
layout: component
---
```html:preview
<sl-tab-group>
<sl-tab slot="nav" panel="general">General</sl-tab>
<sl-tab slot="nav" panel="custom">Custom</sl-tab>
<sl-tab slot="nav" panel="advanced">Advanced</sl-tab>
<sl-tab slot="nav" panel="disabled" disabled>Disabled</sl-tab>
<sl-tab-panel name="general">This is the general tab panel.</sl-tab-panel>
<sl-tab-panel name="custom">This is the custom tab panel.</sl-tab-panel>
<sl-tab-panel name="advanced">This is the advanced tab panel.</sl-tab-panel>
<sl-tab-panel name="disabled">This is a disabled tab panel.</sl-tab-panel>
</sl-tab-group>
```
```jsx:react
import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTabGroup>
<SlTab slot="nav" panel="general">
General
</SlTab>
<SlTab slot="nav" panel="custom">
Custom
</SlTab>
<SlTab slot="nav" panel="advanced">
Advanced
</SlTab>
<SlTab slot="nav" panel="disabled" disabled>
Disabled
</SlTab>
<SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
<SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
<SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
<SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
</SlTabGroup>
);
```
:::tip
Additional demonstrations can be found in the [tab group examples](/components/tab-group).
:::

30
docs/pages/components/tab.md Normal file
View File

@@ -0,0 +1,30 @@
---
meta:
title: Tab
description: Tabs are used inside tab groups to represent and activate tab panels.
layout: component
---
```html:preview
<sl-tab>Tab</sl-tab>
<sl-tab active>Active</sl-tab>
<sl-tab closable>Closable</sl-tab>
<sl-tab disabled>Disabled</sl-tab>
```
```jsx:react
import { SlTab } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlTab>Tab</SlTab>
<SlTab active>Active</SlTab>
<SlTab closable>Closable</SlTab>
<SlTab disabled>Disabled</SlTab>
</>
);
```
:::tip
Additional demonstrations can be found in the [tab group examples](/components/tab-group).
:::

146
docs/pages/components/tag.md Normal file
View File

@@ -0,0 +1,146 @@
---
meta:
title: Tag
description: Tags are used as labels to organize things or to indicate a selection.
layout: component
---
```html:preview
<sl-tag variant="primary">Primary</sl-tag>
<sl-tag variant="success">Success</sl-tag>
<sl-tag variant="neutral">Neutral</sl-tag>
<sl-tag variant="warning">Warning</sl-tag>
<sl-tag variant="danger">Danger</sl-tag>
```
```jsx:react
import { SlTag } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlTag variant="primary">Primary</SlTag>
<SlTag variant="success">Success</SlTag>
<SlTag variant="neutral">Neutral</SlTag>
<SlTag variant="warning">Warning</SlTag>
<SlTag variant="danger">Danger</SlTag>
</>
);
```
## Examples
### Sizes
Use the `size` attribute to change a tab's size.
```html:preview
<sl-tag size="small">Small</sl-tag>
<sl-tag size="medium">Medium</sl-tag>
<sl-tag size="large">Large</sl-tag>
```
```jsx:react
import { SlTag } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlTag size="small">Small</SlTag>
<SlTag size="medium">Medium</SlTag>
<SlTag size="large">Large</SlTag>
</>
);
```
### Pill
Use the `pill` attribute to give tabs rounded edges.
```html:preview
<sl-tag size="small" pill>Small</sl-tag>
<sl-tag size="medium" pill>Medium</sl-tag>
<sl-tag size="large" pill>Large</sl-tag>
```
```jsx:react
import { SlTag } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlTag size="small" pill>
Small
</SlTag>
<SlTag size="medium" pill>
Medium
</SlTag>
<SlTag size="large" pill>
Large
</SlTag>
</>
);
```
### Removable
Use the `removable` attribute to add a remove button to the tag.
```html:preview
<div class="tags-removable">
<sl-tag size="small" removable>Small</sl-tag>
<sl-tag size="medium" removable>Medium</sl-tag>
<sl-tag size="large" removable>Large</sl-tag>
</div>
<script>
const div = document.querySelector('.tags-removable');
div.addEventListener('sl-remove', event => {
const tag = event.target;
tag.style.opacity = '0';
setTimeout(() => (tag.style.opacity = '1'), 2000);
});
</script>
<style>
.tags-removable sl-tag {
transition: var(--sl-transition-medium) opacity;
}
</style>
```
```jsx:react
import { SlTag } from '@shoelace-style/shoelace/dist/react';
const css = `
.tags-removable sl-tag {
transition: var(--sl-transition-medium) opacity;
}
`;
const App = () => {
function handleRemove(event) {
const tag = event.target;
tag.style.opacity = '0';
setTimeout(() => (tag.style.opacity = '1'), 2000);
}
return (
<>
<div className="tags-removable">
<SlTag size="small" removable onSlRemove={handleRemove}>
Small
</SlTag>
<SlTag size="medium" removable onSlRemove={handleRemove}>
Medium
</SlTag>
<SlTag size="large" removable onSlRemove={handleRemove}>
Large
</SlTag>
</div>
<style>{css}</style>
</>
);
};
```

160
docs/pages/components/textarea.md Normal file
View File

@@ -0,0 +1,160 @@
---
meta:
title: Textarea
description: Textareas collect data from the user and allow multiple lines of text.
layout: component
---
```html:preview
<sl-textarea></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea />;
```
:::tip
This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
:::
## Examples
### Labels
Use the `label` attribute to give the textarea an accessible label. For labels that contain HTML, use the `label` slot instead.
```html:preview
<sl-textarea label="Comments"></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea label="Comments" />;
```
### Help Text
Add descriptive help text to a textarea with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
```html:preview
<sl-textarea label="Feedback" help-text="Please tell us what you think."> </sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea label="Feedback" help-text="Please tell us what you think." />;
```
### Rows
Use the `rows` attribute to change the number of text rows that get shown.
```html:preview
<sl-textarea rows="2"></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea rows={2} />;
```
### Placeholders
Use the `placeholder` attribute to add a placeholder.
```html:preview
<sl-textarea placeholder="Type something"></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea placeholder="Type something" />;
```
### Filled Textareas
Add the `filled` attribute to draw a filled textarea.
```html:preview
<sl-textarea placeholder="Type something" filled></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea placeholder="Type something" filled />;
```
### Disabled
Use the `disabled` attribute to disable a textarea.
```html:preview
<sl-textarea placeholder="Textarea" disabled></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea placeholder="Textarea" disabled />;
```
### Sizes
Use the `size` attribute to change a textarea's size.
```html:preview
<sl-textarea placeholder="Small" size="small"></sl-textarea>
<br />
<sl-textarea placeholder="Medium" size="medium"></sl-textarea>
<br />
<sl-textarea placeholder="Large" size="large"></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<>
<SlTextarea placeholder="Small" size="small"></SlTextarea>
<br />
<SlTextarea placeholder="Medium" size="medium"></SlTextarea>
<br />
<SlTextarea placeholder="Large" size="large"></SlTextarea>
</>
);
```
### Prevent Resizing
By default, textareas can be resized vertically by the user. To prevent resizing, set the `resize` attribute to `none`.
```html:preview
<sl-textarea resize="none"></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea resize="none" />;
```
### Expand with Content
Textareas will automatically resize to expand to fit their content when `resize` is set to `auto`.
```html:preview
<sl-textarea resize="auto"></sl-textarea>
```
```jsx:react
import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => <SlTextarea resize="auto" />;
```

431
docs/pages/components/tooltip.md Normal file
View File

@@ -0,0 +1,431 @@
---
meta:
title: Tooltip
description: Tooltips display additional information based on a specific action.
layout: component
---
A tooltip's target is its _first child element_, so you should only wrap one element inside of the tooltip. If you need the tooltip to show up for multiple elements, nest them inside a container first.
Tooltips use `display: contents` so they won't interfere with how elements are positioned in a flex or grid layout.
```html:preview
<sl-tooltip content="This is a tooltip">
<sl-button>Hover Me</sl-button>
</sl-tooltip>
```
```jsx:react
import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTooltip content="This is a tooltip">
<SlButton>Hover Me</SlButton>
</SlTooltip>
);
```
## Examples
### Placement
Use the `placement` attribute to set the preferred placement of the tooltip.
```html:preview
<div class="tooltip-placement-example">
<div class="tooltip-placement-example-row">
<sl-tooltip content="top-start" placement="top-start">
<sl-button></sl-button>
</sl-tooltip>
<sl-tooltip content="top" placement="top">
<sl-button></sl-button>
</sl-tooltip>
<sl-tooltip content="top-end" placement="top-end">
<sl-button></sl-button>
</sl-tooltip>
</div>
<div class="tooltip-placement-example-row">
<sl-tooltip content="left-start" placement="left-start">
<sl-button></sl-button>
</sl-tooltip>
<sl-tooltip content="right-start" placement="right-start">
<sl-button></sl-button>
</sl-tooltip>
</div>
<div class="tooltip-placement-example-row">
<sl-tooltip content="left" placement="left">
<sl-button></sl-button>
</sl-tooltip>
<sl-tooltip content="right" placement="right">
<sl-button></sl-button>
</sl-tooltip>
</div>
<div class="tooltip-placement-example-row">
<sl-tooltip content="left-end" placement="left-end">
<sl-button></sl-button>
</sl-tooltip>
<sl-tooltip content="right-end" placement="right-end">
<sl-button></sl-button>
</sl-tooltip>
</div>
<div class="tooltip-placement-example-row">
<sl-tooltip content="bottom-start" placement="bottom-start">
<sl-button></sl-button>
</sl-tooltip>
<sl-tooltip content="bottom" placement="bottom">
<sl-button></sl-button>
</sl-tooltip>
<sl-tooltip content="bottom-end" placement="bottom-end">
<sl-button></sl-button>
</sl-tooltip>
</div>
</div>
<style>
.tooltip-placement-example {
width: 250px;
margin: 1rem;
}
.tooltip-placement-example-row:after {
content: '';
display: table;
clear: both;
}
.tooltip-placement-example sl-button {
float: left;
width: 2.5rem;
margin-right: 0.25rem;
margin-bottom: 0.25rem;
}
.tooltip-placement-example-row:nth-child(1) sl-tooltip:first-child sl-button,
.tooltip-placement-example-row:nth-child(5) sl-tooltip:first-child sl-button {
margin-left: calc(40px + 0.25rem);
}
.tooltip-placement-example-row:nth-child(2) sl-tooltip:nth-child(2) sl-button,
.tooltip-placement-example-row:nth-child(3) sl-tooltip:nth-child(2) sl-button,
.tooltip-placement-example-row:nth-child(4) sl-tooltip:nth-child(2) sl-button {
margin-left: calc((40px * 3) + (0.25rem * 3));
}
</style>
```
```jsx:react
import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const css = `
.tooltip-placement-example {
width: 250px;
}
.tooltip-placement-example-row:after {
content: '';
display: table;
clear: both;
}
.tooltip-placement-example sl-button {
float: left;
width: 2.5rem;
margin-right: 0.25rem;
margin-bottom: 0.25rem;
}
.tooltip-placement-example-row:nth-child(1) sl-tooltip:first-child sl-button,
.tooltip-placement-example-row:nth-child(5) sl-tooltip:first-child sl-button {
margin-left: calc(40px + 0.25rem);
}
.tooltip-placement-example-row:nth-child(2) sl-tooltip:nth-child(2) sl-button,
.tooltip-placement-example-row:nth-child(3) sl-tooltip:nth-child(2) sl-button,
.tooltip-placement-example-row:nth-child(4) sl-tooltip:nth-child(2) sl-button {
margin-left: calc((40px * 3) + (0.25rem * 3));
}
`;
const App = () => (
<>
<div className="tooltip-placement-example">
<div className="tooltip-placement-example-row">
<SlTooltip content="top-start" placement="top-start">
<SlButton />
</SlTooltip>
<SlTooltip content="top" placement="top">
<SlButton />
</SlTooltip>
<SlTooltip content="top-end" placement="top-end">
<SlButton />
</SlTooltip>
</div>
<div className="tooltip-placement-example-row">
<SlTooltip content="left-start" placement="left-start">
<SlButton />
</SlTooltip>
<SlTooltip content="right-start" placement="right-start">
<SlButton />
</SlTooltip>
</div>
<div className="tooltip-placement-example-row">
<SlTooltip content="left" placement="left">
<SlButton />
</SlTooltip>
<SlTooltip content="right" placement="right">
<SlButton />
</SlTooltip>
</div>
<div className="tooltip-placement-example-row">
<SlTooltip content="left-end" placement="left-end">
<SlButton />
</SlTooltip>
<SlTooltip content="right-end" placement="right-end">
<SlButton />
</SlTooltip>
</div>
<div className="tooltip-placement-example-row">
<SlTooltip content="bottom-start" placement="bottom-start">
<SlButton />
</SlTooltip>
<SlTooltip content="bottom" placement="bottom">
<SlButton />
</SlTooltip>
<SlTooltip content="bottom-end" placement="bottom-end">
<SlButton />
</SlTooltip>
</div>
</div>
<style>{css}</style>
</>
);
```
### Click Trigger
Set the `trigger` attribute to `click` to toggle the tooltip on click instead of hover.
```html:preview
<sl-tooltip content="Click again to dismiss" trigger="click">
<sl-button>Click to Toggle</sl-button>
</sl-tooltip>
```
```jsx:react
import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTooltip content="Click again to dismiss" trigger="click">
<SlButton>Click to Toggle</SlButton>
</SlTooltip>
);
```
### Manual Trigger
Tooltips can be controller programmatically by setting the `trigger` attribute to `manual`. Use the `open` attribute to control when the tooltip is shown.
```html:preview
<sl-button style="margin-right: 4rem;">Toggle Manually</sl-button>
<sl-tooltip content="This is an avatar" trigger="manual" class="manual-tooltip">
<sl-avatar label="User"></sl-avatar>
</sl-tooltip>
<script>
const tooltip = document.querySelector('.manual-tooltip');
const toggle = tooltip.previousElementSibling;
toggle.addEventListener('click', () => (tooltip.open = !tooltip.open));
</script>
```
{% raw %}
```jsx:react
import { useState } from 'react';
import { SlAvatar, SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [open, setOpen] = useState(false);
return (
<>
<SlButton style={{ marginRight: '4rem' }} onClick={() => setOpen(!open)}>
Toggle Manually
</SlButton>
<SlTooltip open={open} content="This is an avatar" trigger="manual">
<SlAvatar />
</SlTooltip>
</>
);
};
```
{% endraw %}
### Removing Arrows
You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token. To remove them, set the value to `0` as shown below.
```html:preview
<sl-tooltip content="This is a tooltip" style="--sl-tooltip-arrow-size: 0;">
<sl-button>No Arrow</sl-button>
</sl-tooltip>
```
{% raw %}
```jsx:react
import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<div style={{ '--sl-tooltip-arrow-size': '0' }}>
<SlTooltip content="This is a tooltip">
<SlButton>Above</SlButton>
</SlTooltip>
<SlTooltip content="This is a tooltip" placement="bottom">
<SlButton>Below</SlButton>
</SlTooltip>
</div>
);
```
{% endraw %}
To override it globally, set it in a root block in your stylesheet after the Shoelace stylesheet is loaded.
```css
:root {
--sl-tooltip-arrow-size: 0;
}
```
### HTML in Tooltips
Use the `content` slot to create tooltips with HTML content. Tooltips are designed only for text and presentational elements. Avoid placing interactive content, such as buttons, links, and form controls, in a tooltip.
```html:preview
<sl-tooltip>
<div slot="content">I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!</div>
<sl-button>Hover me</sl-button>
</sl-tooltip>
```
```jsx:react
import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTooltip>
<div slot="content">
I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!
</div>
<SlButton>Hover Me</SlButton>
</SlTooltip>
);
```
### Setting a Maximum Width
Use the `--max-width` custom property to change the width the tooltip can grow to before wrapping occurs.
```html:preview
<sl-tooltip style="--max-width: 80px;" content="This tooltip will wrap after only 80 pixels.">
<sl-button>Hover me</sl-button>
</sl-tooltip>
```
{% raw %}
```jsx:react
import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTooltip style={{ '--max-width': '80px' }} content="This tooltip will wrap after only 80 pixels.">
<SlButton>Hover Me</SlButton>
</SlTooltip>
);
```
{% endraw %}
### Hoisting
Tooltips will be clipped if they're inside a container that has `overflow: auto|hidden|scroll`. The `hoist` attribute forces the tooltip to use a fixed positioning strategy, allowing it to break out of the container. In this case, the tooltip will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
```html:preview
<div class="tooltip-hoist">
<sl-tooltip content="This is a tooltip">
<sl-button>No Hoist</sl-button>
</sl-tooltip>
<sl-tooltip content="This is a tooltip" hoist>
<sl-button>Hoist</sl-button>
</sl-tooltip>
</div>
<style>
.tooltip-hoist {
position: relative;
border: solid 2px var(--sl-panel-border-color);
overflow: hidden;
padding: var(--sl-spacing-medium);
}
</style>
```
```jsx:react
import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
const css = `
.tooltip-hoist {
border: solid 2px var(--sl-panel-border-color);
overflow: hidden;
padding: var(--sl-spacing-medium);
position: relative;
}
`;
const App = () => (
<>
<div class="tooltip-hoist">
<SlTooltip content="This is a tooltip">
<SlButton>No Hoist</SlButton>
</SlTooltip>
<SlTooltip content="This is a tooltip" hoist>
<SlButton>Hoist</SlButton>
</SlTooltip>
</div>
<style>{css}</style>
</>
);
```

164
docs/pages/components/tree-item.md Normal file
View File

@@ -0,0 +1,164 @@
---
meta:
title: Tree Item
description: A tree item serves as a hierarchical node that lives inside a tree.
layout: component
---
```html:preview
<sl-tree>
<sl-tree-item>
Item 1
<sl-tree-item>Item A</sl-tree-item>
<sl-tree-item>Item B</sl-tree-item>
<sl-tree-item>Item C</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item 2</sl-tree-item>
<sl-tree-item>Item 3</sl-tree-item>
</sl-tree>
```
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTree>
<SlTreeItem>
Item 1
<SlTreeItem>Item A</SlTreeItem>
<SlTreeItem>Item B</SlTreeItem>
<SlTreeItem>Item C</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item 2</SlTreeItem>
<SlTreeItem>Item 3</SlTreeItem>
</SlTree>
);
```
## Examples
### Nested tree items
A tree item can contain other tree items. This allows the node to be expanded or collapsed by the user.
```html:preview
<sl-tree>
<sl-tree-item>
Item 1
<sl-tree-item>
Item A
<sl-tree-item>Item Z</sl-tree-item>
<sl-tree-item>Item Y</sl-tree-item>
<sl-tree-item>Item X</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item B</sl-tree-item>
<sl-tree-item>Item C</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item 2</sl-tree-item>
<sl-tree-item>Item 3</sl-tree-item>
</sl-tree>
```
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTree>
<SlTreeItem>
Item 1
<SlTreeItem>
Item A
<SlTreeItem>Item Z</SlTreeItem>
<SlTreeItem>Item Y</SlTreeItem>
<SlTreeItem>Item X</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item B</SlTreeItem>
<SlTreeItem>Item C</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item 2</SlTreeItem>
<SlTreeItem>Item 3</SlTreeItem>
</SlTree>
);
```
### Selected
Use the `selected` attribute to select a tree item initially.
```html:preview
<sl-tree>
<sl-tree-item selected>
Item 1
<sl-tree-item>Item A</sl-tree-item>
<sl-tree-item>Item B</sl-tree-item>
<sl-tree-item>Item C</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item 2</sl-tree-item>
<sl-tree-item>Item 3</sl-tree-item>
</sl-tree>
```
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTree>
<SlTreeItem selected>
Item 1
<SlTreeItem>Item A</SlTreeItem>
<SlTreeItem>Item B</SlTreeItem>
<SlTreeItem>Item C</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item 2</SlTreeItem>
<SlTreeItem>Item 3</SlTreeItem>
</SlTree>
);
```
### Expanded
Use the `expanded` attribute to expand a tree item initially.
```html:preview
<sl-tree>
<sl-tree-item expanded>
Item 1
<sl-tree-item expanded>
Item A
<sl-tree-item>Item Z</sl-tree-item>
<sl-tree-item>Item Y</sl-tree-item>
<sl-tree-item>Item X</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item B</sl-tree-item>
<sl-tree-item>Item C</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item 2</sl-tree-item>
<sl-tree-item>Item 3</sl-tree-item>
</sl-tree>
```
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTree>
<SlTreeItem expanded>
Item 1
<SlTreeItem expanded>
Item A
<SlTreeItem>Item Z</SlTreeItem>
<SlTreeItem>Item Y</SlTreeItem>
<SlTreeItem>Item X</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item B</SlTreeItem>
<SlTreeItem>Item C</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item 2</SlTreeItem>
<SlTreeItem>Item 3</SlTreeItem>
</SlTree>
);
```

469
docs/pages/components/tree.md Normal file
View File

@@ -0,0 +1,469 @@
---
meta:
title: Tree
description: Trees allow you to display a hierarchical list of selectable tree items. Items with children can be expanded and collapsed as desired by the user.
layout: component
---
```html:preview
<sl-tree>
<sl-tree-item>
Deciduous
<sl-tree-item>Birch</sl-tree-item>
<sl-tree-item>
Maple
<sl-tree-item>Field maple</sl-tree-item>
<sl-tree-item>Red maple</sl-tree-item>
<sl-tree-item>Sugar maple</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Oak</sl-tree-item>
</sl-tree-item>
<sl-tree-item>
Coniferous
<sl-tree-item>Cedar</sl-tree-item>
<sl-tree-item>Pine</sl-tree-item>
<sl-tree-item>Spruce</sl-tree-item>
</sl-tree-item>
<sl-tree-item>
Non-trees
<sl-tree-item>Bamboo</sl-tree-item>
<sl-tree-item>Cactus</sl-tree-item>
<sl-tree-item>Fern</sl-tree-item>
</sl-tree-item>
</sl-tree>
```
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTree>
<SlTreeItem>
Deciduous
<SlTreeItem>Birch</SlTreeItem>
<SlTreeItem>
Maple
<SlTreeItem>Field maple</SlTreeItem>
<SlTreeItem>Red maple</SlTreeItem>
<SlTreeItem>Sugar maple</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Oak</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
Coniferous
<SlTreeItem>Cedar</SlTreeItem>
<SlTreeItem>Pine</SlTreeItem>
<SlTreeItem>Spruce</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
Non-trees
<SlTreeItem>Bamboo</SlTreeItem>
<SlTreeItem>Cactus</SlTreeItem>
<SlTreeItem>Fern</SlTreeItem>
</SlTreeItem>
</SlTree>
);
```
## Examples
### Selection Modes
The `selection` attribute lets you change the selection behavior of the tree.
- Use `single` to allow the selection of a single item (default).
- Use `multiple` to allow the selection of multiple items.
- Use `leaf` to only allow leaf nodes to be selected.
```html:preview
<sl-select id="selection-mode" value="single" label="Selection">
<sl-option value="single">Single</sl-option>
<sl-option value="multiple">Multiple</sl-option>
<sl-option value="leaf">Leaf</sl-option>
</sl-select>
<br />
<sl-tree class="tree-selectable">
<sl-tree-item>
Item 1
<sl-tree-item>
Item A
<sl-tree-item>Item Z</sl-tree-item>
<sl-tree-item>Item Y</sl-tree-item>
<sl-tree-item>Item X</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item B</sl-tree-item>
<sl-tree-item>Item C</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Item 2</sl-tree-item>
<sl-tree-item>Item 3</sl-tree-item>
</sl-tree>
<script>
const selectionMode = document.querySelector('#selection-mode');
const tree = document.querySelector('.tree-selectable');
selectionMode.addEventListener('sl-change', () => {
tree.querySelectorAll('sl-tree-item').forEach(item => (item.selected = false));
tree.selection = selectionMode.value;
});
</script>
```
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [selection, setSelection] = useState('single');
return (
<>
<SlSelect label="Selection" value={selection} onSlChange={event => setSelection(event.target.value)}>
<SlMenuItem value="single">single</SlMenuItem>
<SlMenuItem value="multiple">multiple</SlMenuItem>
<SlMenuItem value="leaf">leaf</SlMenuItem>
</SlSelect>
<br />
<SlTree selection={selection}>
<SlTreeItem>
Item 1
<SlTreeItem>
Item A
<SlTreeItem>Item Z</SlTreeItem>
<SlTreeItem>Item Y</SlTreeItem>
<SlTreeItem>Item X</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item B</SlTreeItem>
<SlTreeItem>Item C</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Item 2</SlTreeItem>
<SlTreeItem>Item 3</SlTreeItem>
</SlTree>
</>
);
};
```
### Showing Indent Guides
Indent guides can be drawn by setting `--indent-guide-width`. You can also change the color, offset, and style, using `--indent-guide-color`, `--indent-guide-style`, and `--indent-guide-offset`, respectively.
```html:preview
<sl-tree class="tree-with-lines">
<sl-tree-item expanded>
Deciduous
<sl-tree-item>Birch</sl-tree-item>
<sl-tree-item expanded>
Maple
<sl-tree-item>Field maple</sl-tree-item>
<sl-tree-item>Red maple</sl-tree-item>
<sl-tree-item>Sugar maple</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Oak</sl-tree-item>
</sl-tree-item>
<sl-tree-item>
Coniferous
<sl-tree-item>Cedar</sl-tree-item>
<sl-tree-item>Pine</sl-tree-item>
<sl-tree-item>Spruce</sl-tree-item>
</sl-tree-item>
<sl-tree-item>
Non-trees
<sl-tree-item>Bamboo</sl-tree-item>
<sl-tree-item>Cactus</sl-tree-item>
<sl-tree-item>Fern</sl-tree-item>
</sl-tree-item>
</sl-tree>
<style>
.tree-with-lines {
--indent-guide-width: 1px;
}
</style>
```
{% raw %}
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTree class="tree-with-lines" style={{ '--indent-guide-width': '1px' }}>
<SlTreeItem expanded>
Deciduous
<SlTreeItem>Birch</SlTreeItem>
<SlTreeItem expanded>
Maple
<SlTreeItem>Field maple</SlTreeItem>
<SlTreeItem>Red maple</SlTreeItem>
<SlTreeItem>Sugar maple</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Oak</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
Coniferous
<SlTreeItem>Cedar</SlTreeItem>
<SlTreeItem>Pine</SlTreeItem>
<SlTreeItem>Spruce</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
Non-trees
<SlTreeItem>Bamboo</SlTreeItem>
<SlTreeItem>Cactus</SlTreeItem>
<SlTreeItem>Fern</SlTreeItem>
</SlTreeItem>
</SlTree>
);
```
{% endraw %}
### Lazy Loading
Use the `lazy` attribute on a tree item to indicate that the content is not yet present and will be loaded later. When the user tries to expand the node, the `loading` state is set to `true` and the `sl-lazy-load` event will be emitted to allow you to load data asynchronously. The item will remain in a loading state until its content is changed.
If you want to disable this behavior after the first load, simply remove the `lazy` attribute and, on the next expand, the existing content will be shown instead.
```html:preview
<sl-tree>
<sl-tree-item lazy>Available Trees</sl-tree-item>
</sl-tree>
<script type="module">
const lazyItem = document.querySelector('sl-tree-item[lazy]');
lazyItem.addEventListener('sl-lazy-load', () => {
// Simulate asynchronous loading
setTimeout(() => {
const subItems = ['Birch', 'Cedar', 'Maple', 'Pine'];
for (const item of subItems) {
const treeItem = document.createElement('sl-tree-item');
treeItem.innerText = item;
lazyItem.append(treeItem);
}
// Disable lazy mode once the content has been loaded
lazyItem.lazy = false;
}, 1000);
});
</script>
```
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [childItems, setChildItems] = useState([]);
const [lazy, setLazy] = useState(true);
const handleLazyLoad = () => {
// Simulate asynchronous loading
setTimeout(() => {
setChildItems(['Birch', 'Cedar', 'Maple', 'Pine']);
// Disable lazy mode once the content has been loaded
setLazy(false);
}, 1000);
};
return (
<SlTree>
<SlTreeItem lazy={lazy} onSlLazyLoad={handleLazyLoad}>
Available Trees
{childItems.map(item => (
<SlTreeItem>{item}</SlTreeItem>
))}
</SlTreeItem>
</SlTree>
);
};
```
### Customizing the Expand and Collapse Icons
Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `expand-button` part as shown below.
```html:preview
<sl-tree class="custom-icons">
<sl-icon name="plus-square" slot="expand-icon"></sl-icon>
<sl-icon name="dash-square" slot="collapse-icon"></sl-icon>
<sl-tree-item>
Deciduous
<sl-tree-item>Birch</sl-tree-item>
<sl-tree-item>
Maple
<sl-tree-item>Field maple</sl-tree-item>
<sl-tree-item>Red maple</sl-tree-item>
<sl-tree-item>Sugar maple</sl-tree-item>
</sl-tree-item>
<sl-tree-item>Oak</sl-tree-item>
</sl-tree-item>
<sl-tree-item>
Coniferous
<sl-tree-item>Cedar</sl-tree-item>
<sl-tree-item>Pine</sl-tree-item>
<sl-tree-item>Spruce</sl-tree-item>
</sl-tree-item>
<sl-tree-item>
Non-trees
<sl-tree-item>Bamboo</sl-tree-item>
<sl-tree-item>Cactus</sl-tree-item>
<sl-tree-item>Fern</sl-tree-item>
</sl-tree-item>
</sl-tree>
<style>
.custom-icons sl-tree-item::part(expand-button) {
/* Disable the expand/collapse animation */
rotate: none;
}
</style>
```
<!-- prettier-ignore -->
```jsx:react
import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => (
<SlTree>
<SlIcon name="plus-square" slot="expand-icon"></SlIcon>
<SlIcon name="dash-square" slot="collapse-icon"></SlIcon>
<SlTreeItem>
Deciduous
<SlTreeItem>Birch</SlTreeItem>
<SlTreeItem>
Maple
<SlTreeItem>Field maple</SlTreeItem>
<SlTreeItem>Red maple</SlTreeItem>
<SlTreeItem>Sugar maple</SlTreeItem>
</SlTreeItem>
<SlTreeItem>Oak</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
Coniferous
<SlTreeItem>Cedar</SlTreeItem>
<SlTreeItem>Pine</SlTreeItem>
<SlTreeItem>Spruce</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
Non-trees
<SlTreeItem>Bamboo</SlTreeItem>
<SlTreeItem>Cactus</SlTreeItem>
<SlTreeItem>Fern</SlTreeItem>
</SlTreeItem>
</SlTree>
);
```
### With Icons
Decorative icons can be used before labels to provide hints for each node.
```html:preview
<sl-tree class="tree-with-icons">
<sl-tree-item expanded>
<sl-icon name="folder"></sl-icon>
Documents
<sl-tree-item>
<sl-icon name="folder"> </sl-icon>
Photos
<sl-tree-item>
<sl-icon name="image"></sl-icon>
birds.jpg
</sl-tree-item>
<sl-tree-item>
<sl-icon name="image"></sl-icon>
kitten.jpg
</sl-tree-item>
<sl-tree-item>
<sl-icon name="image"></sl-icon>
puppy.jpg
</sl-tree-item>
</sl-tree-item>
<sl-tree-item>
<sl-icon name="folder"></sl-icon>
Writing
<sl-tree-item>
<sl-icon name="file"></sl-icon>
draft.txt
</sl-tree-item>
<sl-tree-item>
<sl-icon name="file-pdf"></sl-icon>
final.pdf
</sl-tree-item>
<sl-tree-item>
<sl-icon name="file-bar-graph"></sl-icon>
sales.xls
</sl-tree-item>
</sl-tree-item>
</sl-tree-item>
</sl-tree>
```
```jsx:react
import { SlIcon, SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
const App = () => {
return (
<SlTree class="tree-with-icons">
<SlTreeItem expanded>
<SlIcon name="folder" />
Root
<SlTreeItem>
<SlIcon name="folder" />
Folder 1<SlTreeItem>
<SlIcon name="files" />
File 1 - 1
</SlTreeItem>
<SlTreeItem disabled>
<SlIcon name="files" />
File 1 - 2
</SlTreeItem>
<SlTreeItem>
<SlIcon name="files" />
File 1 - 3
</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
<SlIcon name="files" />
Folder 2<SlTreeItem>
<SlIcon name="files" />
File 2 - 1
</SlTreeItem>
<SlTreeItem>
<SlIcon name="files" />
File 2 - 2
</SlTreeItem>
</SlTreeItem>
<SlTreeItem>
<SlIcon name="files" />
File 1
</SlTreeItem>
</SlTreeItem>
</SlTree>
);
};
```

46
docs/pages/components/visually-hidden.md Normal file
View File

@@ -0,0 +1,46 @@
---
meta:
title: Visually Hidden
description: The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
layout: component
---
According to [The A11Y Project](https://www.a11yproject.com/posts/2013-01-11-how-to-hide-content/), "there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."
Since visually hidden content can receive focus when tabbing, the element will become visible when something inside receives focus. This behavior is intentional, as sighted keyboards user won't be able to determine where the focus indicator is without it.
```html:preview
<div style="min-height: 1.875rem;">
<sl-visually-hidden>
<a href="#">Skip to main content</a>
</sl-visually-hidden>
</div>
```
## Examples
### Links That Open in New Windows
In this example, the link will open a new window. Screen readers will announce "opens in a new window" even though the text content isn't visible to sighted users.
```html:preview
<a href="https://example.com/" target="_blank">
Visit External Page
<sl-icon name="box-arrow-up-right"></sl-icon>
<sl-visually-hidden>opens in a new window</sl-visually-hidden>
</a>
```
### Content Conveyed By Context
Adding a label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content that will be announced by assistive devices such as screen readers.
```html:preview
<sl-card style="width: 100%; max-width: 360px;">
<header>
<sl-visually-hidden>Personal Info</sl-visually-hidden>
</header>
<sl-input label="Name" style="margin-bottom: .5rem;"></sl-input>
<sl-input label="Email" type="email"></sl-input>
</sl-card>
```

88
docs/pages/frameworks/angular.md Normal file
View File

@@ -0,0 +1,88 @@
---
meta:
title: Angular
description: Tips for using Shoelace in your Angular app.
---
# Angular
Angular [plays nice](https://custom-elements-everywhere.com/#angular) with custom elements, so you can use Shoelace in your Angular apps with ease.
## Installation
To add Shoelace to your Angular app, install the package from npm.
```bash
npm install @shoelace-style/shoelace
```
Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
```jsx
import '@shoelace-style/shoelace/dist/themes/light.css';
import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
```
:::tip
If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/dist/assets` into a public folder in your app. Then you can point the base path to that folder instead.
:::
## Configuration
Then make sure to apply the custom elements schema as shown below.
```js
import { BrowserModule } from '@angular/platform-browser';
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { AppComponent } from './app.component';
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule],
providers: [],
bootstrap: [AppComponent],
schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}
```
## Reference Shoelace components in your Angular component code
```js
import { SlDrawer } from '@shoelace-style/shoelace';
@Component({
selector: 'app-drawer-example',
template: '<div id="page"><button (click)="showDrawer()">Show drawer</button><sl-drawer #drawer label="Drawer" class="drawer-focus" style="--size: 50vw"><p>Drawer content</p></sl-drawer></div>'
})
export class DrawerExampleComponent implements OnInit {
// use @ViewChild to get a reference to the #drawer element within component template
@ViewChild('drawer')
drawer?: ElementRef<SlDrawer>;
...
constructor(...) {
}
ngOnInit() {
}
...
showDrawer() {
// use nativeElement to access Shoelace components
this.drawer?.nativeElement.show();
}
}
```
Now you can start using Shoelace components in your app!
:::tip
Are you using Shoelace with Angular? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md)
:::

154
docs/pages/frameworks/react.md Normal file
View File

@@ -0,0 +1,154 @@
---
meta:
title: React
description: Tips for using Shoelace in your React app.
---
# React
Shoelace offers a React version of every component to provide an idiomatic experience for React users. You can easily toggle between HTML and React examples throughout the documentation.
## Installation
To add Shoelace to your React app, install the package from npm.
```bash
npm install @shoelace-style/shoelace
```
Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
```jsx
// App.jsx
import '@shoelace-style/shoelace/dist/themes/light.css';
import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
```
:::tip
If you'd rather not use the CDN for assets, you can create a [build task](https://webpack.js.org/plugins/copy-webpack-plugin/) that copies `node_modules/@shoelace-style/shoelace/dist/assets` into your app's `public` directory. Then you can point the base path to that folder instead.
:::
Now you can start using components!
## Usage
### Importing Components
Every Shoelace component is available to import as a React component. Note that we're importing the `<SlButton>` _React component_ instead of the `<sl-button>` _custom element_ in the example below.
```jsx
import { SlButton } from '@shoelace-style/shoelace/dist/react';
const MyComponent = () => <SlButton variant="primary">Click me</SlButton>;
export default MyComponent;
```
You can find a copy + paste import for each component in the "importing" section of its documentation.
### Event Handling
Many Shoelace components emit [custom events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). For example, the [input component](/components/input) emits the `sl-input` event when it receives input. In React, you can listen for the event using `onSlInput`.
Here's how you can bind the input's value to a state variable.
```jsx
import { useState } from 'react';
import { SlInput } from '@shoelace-style/shoelace/dist/react';
function MyComponent() {
const [value, setValue] = useState('');
return <SlInput value={value} onSlInput={event => setValue(event.target.value)} />;
}
export default MyComponent;
```
If you're using TypeScript, it's important to note that `event.target` will be a reference to the underlying custom element. You can use `(event.target as any).value` as a quick fix, or you can strongly type the event target as shown below.
```tsx
import { useState } from 'react';
import { SlInput } from '@shoelace-style/shoelace/dist/react';
import type SlInputElement from '@shoelace-style/shoelace/dist/components/input/input';
function MyComponent() {
const [value, setValue] = useState('');
return <SlInput value={value} onSlInput={event => setValue((event.target as SlInputElement).value)} />;
}
export default MyComponent;
```
## Testing with Jest
Testing with web components can be challenging if your test environment runs in a Node environment (i.e. it doesn't run in a real browser). Fortunately, [Jest](https://jestjs.io/) has made a number of strides to support web components and provide additional browser APIs. However, it's still not a complete replication of a browser environment.
Here are some tips that will help smooth things over if you're having trouble with Jest + Shoelace.
:::tip
If you're looking for a fast, modern testing alternative, consider [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/).
:::
### Upgrade Jest
Jest underwent a major revamp and received support for web components in [version 26.5.0](https://github.com/facebook/jest/blob/main/CHANGELOG.md#2650) when it introduced [JSDOM 16.2.0](https://github.com/jsdom/jsdom/blob/master/Changelog.md#1620). This release also included a number of mocks for built-in browser functions such as `MutationObserver`, `document.createRange`, and others.
If you're using [Create React App](https://reactjs.org/docs/create-a-new-react-app.html#create-react-app), you can update `react-scripts` which will also update Jest.
```
npm install react-scripts@latest
```
### Mock Missing APIs
Some components use `window.matchMedia`, but this function isn't supported by JSDOM so you'll need to mock it yourself.
In `src/setupTests.js`, add the following.
```js
Object.defineProperty(window, 'matchMedia', {
writable: true,
value: jest.fn().mockImplementation(query => ({
matches: false,
media: query,
onchange: null,
addListener: jest.fn(), // deprecated
removeListener: jest.fn(), // deprecated
addEventListener: jest.fn(),
removeEventListener: jest.fn(),
dispatchEvent: jest.fn()
}))
});
```
For more details, refer to Jest's [manual mocking](https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom) documentation.
### Transform ES Modules
ES Modules are a [well-supported browser standard](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/). This is how Shoelace is distributed, but most React apps expect CommonJS. As a result, you'll probably run into the following error.
```
Error: Unable to import outside of a module
```
To fix this, add the following to your `package.json` which tells the transpiler to process Shoelace modules.
```js
{
"jest": {
"transformIgnorePatterns": ["node_modules/?!(@shoelace)"]
}
}
```
These instructions are for apps created via Create React App. If you're using Jest directly, you can add `transformIgnorePatterns` directly into `jest.config.js`.
For more details, refer to Jest's [`transformIgnorePatterns` customization](https://jestjs.io/docs/tutorial-react-native#transformignorepatterns-customization) documentation.
:::tip
Are you using Shoelace with React? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/react.md)
:::

107
docs/pages/frameworks/vue-2.md Normal file
View File

@@ -0,0 +1,107 @@
---
meta:
title: Vue (version 2)
description: Tips for using Shoelace in your Vue 2 app.
---
# Vue (version 2)
Vue [plays nice](https://custom-elements-everywhere.com/#vue) with custom elements, so you can use Shoelace in your Vue apps with ease.
:::tip
These instructions are for Vue 2. If you're using Vue 3 or above, please see the [Vue 3 instructions](/frameworks/vue).
:::
## Installation
To add Shoelace to your Vue app, install the package from npm.
```bash
npm install @shoelace-style/shoelace
```
Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
```jsx
import '@shoelace-style/shoelace/dist/themes/light.css';
import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
```
:::tip
If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/dist/assets` into a public folder in your app. Then you can point the base path to that folder instead.
:::
## Configuration
You'll need to tell Vue to ignore Shoelace components. This is pretty easy because they all start with `sl-`.
```js
import Vue from 'vue';
import App from './App.vue';
Vue.config.ignoredElements = [/sl-/];
const app = new Vue({
render: h => h(App)
});
app.$mount('#app');
```
Now you can start using Shoelace components in your app!
## Usage
### Binding Complex Data
When binding complex data such as objects and arrays, use the `.prop` modifier to make Vue bind them as a property instead of an attribute.
```html
<sl-color-picker :swatches.prop="mySwatches" />
```
### Two-way Binding
One caveat is there's currently [no support for v-model on custom elements](https://github.com/vuejs/vue/issues/7830), but you can still achieve two-way binding manually.
```html
<!-- This doesn't work -->
<sl-input v-model="name"></sl-input>
<!-- This works, but it's a bit longer -->
<sl-input :value="name" @input="name = $event.target.value"></sl-input>
```
If that's too verbose for your liking, you can use a custom directive instead. [This utility](https://www.npmjs.com/package/@shoelace-style/vue-sl-model) adds a custom directive that will work just like `v-model` but for Shoelace components. To install it, use this command.
```bash
npm install @shoelace-style/vue-sl-model@1
```
Next, import the directive and enable it like this.
```js
import Vue from 'vue';
import ShoelaceModelDirective from '@shoelace-style/vue-sl-model';
import App from './App.vue';
Vue.use(ShoelaceModelDirective);
Vue.config.ignoredElements = [/sl-/];
const app = new Vue({
render: h => h(App)
});
app.$mount('#app');
```
Now you can use the `v-sl-model` directive to keep your data in sync!
```html
<sl-input v-sl-model="name"></sl-input>
```
:::tip
Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue-2.md)
:::

127
docs/pages/frameworks/vue.md Normal file
View File

@@ -0,0 +1,127 @@
---
meta:
title: Vue
description: Tips for using Shoelace in your Vue 3 app.
---
# Vue
Vue [plays nice](https://custom-elements-everywhere.com/#vue) with custom elements, so you can use Shoelace in your Vue apps with ease.
:::tip
These instructions are for Vue 3 and above. If you're using Vue 2, please see the [Vue 2 instructions](/frameworks/vue-2).
:::
## Installation
To add Shoelace to your Vue app, install the package from npm.
```bash
npm install @shoelace-style/shoelace
```
Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
```jsx
import '@shoelace-style/shoelace/dist/themes/light.css';
import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
```
:::tip
If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/dist/assets` into a public folder in your app. Then you can point the base path to that folder instead.
:::
## Configuration
You'll need to tell Vue to ignore Shoelace components. This is pretty easy because they all start with `sl-`.
```js
import { fileURLToPath, URL } from 'url';
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: tag => tag.startsWith('sl-')
}
}
})
],
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url))
}
}
});
```
Now you can start using Shoelace components in your app!
## Usage
### QR code generator example
```html
<template>
<div class="container">
<h1>QR code generator</h1>
<sl-input maxlength="255" clearable label="Value" v-model="qrCode"></sl-input>
<sl-qr-code :value="qrCode"></sl-qr-code>
</div>
</template>
<script setup>
import { ref } from 'vue';
import '@shoelace-style/shoelace/dist/components/qr-code/qr-code.js';
import '@shoelace-style/shoelace/dist/components/input/input.js';
const qrCode = ref();
</script>
<style>
.container {
max-width: 400px;
margin: 0 auto;
}
sl-input {
margin: var(--sl-spacing-large) 0;
}
</style>
```
### Binding Complex Data
When binding complex data such as objects and arrays, use the `.prop` modifier to make Vue bind them as a property instead of an attribute.
```html
<sl-color-picker :swatches.prop="mySwatches" />
```
:::tip
Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md)
:::
### Slots
To use Shoelace components with slots, follow the Vue documentation on using [slots with custom elements](https://vuejs.org/guide/extras/web-components.html#building-custom-elements-with-vue).
Here is an example:
```html
<sl-drawer label="Drawer" placement="start" class="drawer-placement-start" :open="drawerIsOpen">
This drawer slides in from the start.
<div slot="footer">
<sl-button variant="primary" @click=" drawerIsOpen = false">Close</sl-button>
</div>
</sl-drawer>
```

165
docs/pages/getting-started/customizing.md Normal file
View File

@@ -0,0 +1,165 @@
---
meta:
title: Customizing
description: Learn how to customize Shoelace through parts and custom properties.
---
# Customizing
Shoelace components can be customized at a high level through design tokens. This gives you control over theme colors and general styling. For more advanced customizations, you can make use of component parts and custom properties to target individual components.
## Design Tokens
Shoelace makes use of several design tokens to provide a consistent appearance across components. You can customize them and use them in your own application with pure CSS — no preprocessor required.
Design tokens offer a high-level way to customize the library with minimal effort. There are no component-specific variables, however, as design tokens are intended to be generic and highly reusable. To customize an individual component, refer to the section entitled [Component Parts](#component-parts).
Design tokens are accessed through CSS custom properties that are defined in your theme. Because design tokens live at the page level, they're prefixed with `--sl-` to avoid collisions with other libraries.
To customize a design token, simply override it in your stylesheet using a `:root` block. Here's an example that changes the primary theme to purple based on existing [color primitives](/tokens/color#primitives).
```css
:root {
/* Changes the primary theme color to purple using primitives */
--sl-color-primary-50: var(--sl-color-purple-50);
--sl-color-primary-100: var(--sl-color-purple-100);
--sl-color-primary-200: var(--sl-color-purple-200);
--sl-color-primary-300: var(--sl-color-purple-300);
--sl-color-primary-400: var(--sl-color-purple-400);
--sl-color-primary-500: var(--sl-color-purple-500);
--sl-color-primary-600: var(--sl-color-purple-600);
--sl-color-primary-700: var(--sl-color-purple-700);
--sl-color-primary-800: var(--sl-color-purple-800);
--sl-color-primary-900: var(--sl-color-purple-900);
--sl-color-primary-950: var(--sl-color-purple-950);
}
```
Many design tokens are described further along in this documentation. For a complete list, refer to `src/themes/light.css` in the project's [source code](https://github.com/shoelace-style/shoelace/blob/current/src/themes/light.css).
## Component Parts
Whereas design tokens offer a high-level way to customize the library, component parts offer a low-level way to customize individual components. Again, this is done with pure CSS — no preprocessor required.
Shoelace components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate their styles and behaviors. As a result, you can't simply target their internals with the usual CSS selectors. Instead, components expose "parts" that can be targeted with the [CSS part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), or `::part()`.
Here's an example that modifies buttons with the `tomato-button` class.
```html:preview
<sl-button class="tomato-button"> Tomato Button </sl-button>
<style>
.tomato-button::part(base) {
background: var(--sl-color-neutral-0);
border: solid 1px tomato;
}
.tomato-button::part(base):hover {
background: rgba(255, 99, 71, 0.1);
}
.tomato-button::part(base):active {
background: rgba(255, 99, 71, 0.2);
}
.tomato-button::part(base):focus-visible {
box-shadow: 0 0 0 3px rgba(255, 99, 71, 0.33);
}
.tomato-button::part(label) {
color: tomato;
}
</style>
```
At first glance, this approach might seem a bit verbose or even limiting, but it comes with a few important advantages:
- Customizations can be made to components with explicit selectors, such as `::part(icon)`, rather than implicit selectors, such as `.button > div > span + .icon`, that are much more fragile.
- The internal structure of a component will likely change as it evolves. By exposing component parts through an API, the internals can be reworked without fear of breaking customizations as long as its parts remain intact.
- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.
## Custom Properties
For convenience, some components expose CSS custom properties you can override. These are not design tokens, nor do they have the same `--sl-` prefix since they're scoped to a component.
You can set custom properties on a component in your stylesheet.
```css
sl-avatar {
--size: 6rem;
}
```
This will also work if you need to target a subset of components with a specific class.
```css
sl-avatar.your-class {
--size: 6rem;
}
```
Alternatively, you can set them inline directly on the element.
```html
<sl-avatar style="--size: 6rem;"></sl-avatar>
```
Not all components expose CSS custom properties. For those that do, they can be found in the component's API documentation.
## Animations
Some components use animation, such as when a dialog is shown or hidden. Animations are performed using the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) rather than CSS. However, you can still customize them through Shoelace's animation registry. If a component has customizable animations, they'll be listed in the "Animation" section of its documentation.
To customize a default animation, use the `setDefaultAnimation()` method. The function accepts an animation name (found in the component's docs) and an object with `keyframes`, and `options` or `null` to disable the animation.
This example will make all dialogs use a custom show animation.
```js
import { setDefaultAnimation } from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
// Change the default animation for all dialogs
setDefaultAnimation('dialog.show', {
keyframes: [
{ transform: 'rotate(-10deg) scale(0.5)', opacity: '0' },
{ transform: 'rotate(0deg) scale(1)', opacity: '1' }
],
options: {
duration: 500
}
});
```
:::tip
To support RTL languages in your animation, you can pass an additional property called `rtlKeyframes`. This property shares the same type as `keyframes` and will be automatically used when the component's directionality is RTL. If `rtlKeyframes` is not provided, `keyframes` will be used as a fallback.
:::
If you only want to target a single component, use the `setAnimation()` method instead. This function accepts an element, an animation name, and an object comprised of animation `keyframes` and `options`.
In this example, only the target dialog will use a custom show animation.
```js
import { setAnimation } from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
// Change the animation for a single dialog
const dialog = document.querySelector('#my-dialog');
setAnimation(dialog, 'dialog.show', {
keyframes: [
{ transform: 'rotate(-10deg) scale(0.5)', opacity: '0' },
{ transform: 'rotate(0deg) scale(1)', opacity: '1' }
],
options: {
duration: 500
}
});
```
To learn more about creating Web Animations, refer to the documentation for [`Element.animate()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate).
:::tip
Animations respect the users `prefers-reduced-motion` setting. When this setting is enabled, animations will not be played. To disable animations for all users, pass in `null` instead of a keyframes/options object.
:::

515
docs/pages/getting-started/form-controls.md Normal file
View File

@@ -0,0 +1,515 @@
---
meta:
title: Form Controls
description: Some things to note about Shoelace and forms.
---
# Form Controls
Every Shoelace component makes use of a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate markup, styles, and behavior. One caveat of this approach is that native `<form>` elements do not recognize form controls located inside a shadow root.
Shoelace solves this problem by using the [`formdata`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/formdata_event) event, which is [available in all modern browsers](https://caniuse.com/mdn-api_htmlformelement_formdata_event). This means, when a form is submitted, Shoelace form controls will automatically append their values to the `FormData` object that's used to submit the form. In most cases, things will "just work." However, if you're using a form serialization library, it might need to be adapted to recognize Shoelace form controls.
:::tip
Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject data and trigger validation as necessary. If you're also attaching an event listener to the form, _you must attach it after Shoelace form controls are connected to the DOM_, otherwise your logic will run before Shoelace has a chance to inject form data and validate form controls.
:::
## Data Serialization
Serialization is just a fancy word for collecting form data. If you're relying on standard form submissions, e.g. `<form action="...">`, you can probably skip this section. However, most modern apps use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or a library such as [axios](https://github.com/axios/axios) to submit forms using JavaScript.
The [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) interface offers a standard way to serialize forms in the browser. You can create a `FormData` object from any `<form>` element like this.
```js
const form = document.querySelector('form');
const data = new FormData(form);
// All form control data is available in a FormData object
```
However, some folks find `FormData` tricky to work with or they need to pass a JSON payload to their server. To accommodate this, Shoelace offers a serialization utility that gathers form data and returns a simple JavaScript object instead.
```js
import { serialize } from '@shoelace-style/shoelace/dist/utilities/form.js';
const form = document.querySelector('form');
const data = serialize(form);
// All form control data is available in a plain object
```
This results in an object with name/value pairs that map to each form control. If more than one form control shares the same name, the values will be passed as an array, e.g. `{ name: ['value1', 'value2'] }`.
## Constraint Validation
Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Shoelace form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. Shoelace implements many of the same attributes as native form controls, but check the documentation for a list of supported properties for each component.
If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `<form>` element.
:::tip
If this syntax looks unfamiliar, don't worry! Most of what you're learning on this page is platform knowledge that applies to regular form controls, too.
:::
:::warning
Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. **You should always validate and sanitize user input on the server!**
:::
### Required Fields
To make a field required, use the `required` attribute. Required fields will automatically receive a `*` after their labels. This is configurable through the `--sl-input-required-content` custom property.
The form will not be submitted if a required field is incomplete.
```html:preview
<form class="input-validation-required">
<sl-input name="name" label="Name" required></sl-input>
<br />
<sl-select label="Favorite Animal" clearable required>
<sl-option value="birds">Birds</sl-option>
<sl-option value="cats">Cats</sl-option>
<sl-option value="dogs">Dogs</sl-option>
<sl-option value="other">Other</sl-option>
</sl-select>
<br />
<sl-textarea name="comment" label="Comment" required></sl-textarea>
<br />
<sl-checkbox required>Check me before submitting</sl-checkbox>
<br /><br />
<sl-button type="submit" variant="primary">Submit</sl-button>
</form>
<script type="module">
const form = document.querySelector('.input-validation-required');
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
</script>
```
```jsx:react
import { SlButton, SlCheckbox, SlInput, SlMenuItem, SlSelect, SlTextarea } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleSubmit(event) {
event.preventDefault();
alert('All fields are valid!');
}
return (
<form onSubmit={handleSubmit}>
<SlInput name="name" label="Name" required />
<br />
<SlSelect label="Favorite Animal" clearable required>
<SlMenuItem value="birds">Birds</SlMenuItem>
<SlMenuItem value="cats">Cats</SlMenuItem>
<SlMenuItem value="dogs">Dogs</SlMenuItem>
<SlMenuItem value="other">Other</SlMenuItem>
</SlSelect>
<br />
<SlTextarea name="comment" label="Comment" required></SlTextarea>
<br />
<SlCheckbox required>Check me before submitting</SlCheckbox>
<br />
<br />
<SlButton type="submit" variant="primary">
Submit
</SlButton>
</form>
);
};
```
### Input Patterns
To restrict a value to a specific [pattern](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern), use the `pattern` attribute. This example only allows the letters A-Z, so the form will not submit if a number or symbol is entered. This only works with `<sl-input>` elements.
```html:preview
<form class="input-validation-pattern">
<sl-input name="letters" required label="Letters" pattern="[A-Za-z]+"></sl-input>
<br />
<sl-button type="submit" variant="primary">Submit</sl-button>
<sl-button type="reset" variant="default">Reset</sl-button>
</form>
<script type="module">
const form = document.querySelector('.input-validation-pattern');
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
</script>
```
```jsx:react
import { SlButton, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleSubmit(event) {
event.preventDefault();
alert('All fields are valid!');
}
return (
<form onSubmit={handleSubmit}>
<SlInput name="letters" required label="Letters" pattern="[A-Za-z]+" />
<br />
<SlButton type="submit" variant="primary">
Submit
</SlButton>
</form>
);
};
```
### Input Types
Some input types will automatically trigger constraints, such as `email` and `url`.
```html:preview
<form class="input-validation-type">
<sl-input type="email" label="Email" placeholder="you@example.com" required></sl-input>
<br />
<sl-input type="url" label="URL" placeholder="https://example.com/" required></sl-input>
<br />
<sl-button type="submit" variant="primary">Submit</sl-button>
<sl-button type="reset" variant="default">Reset</sl-button>
</form>
<script type="module">
const form = document.querySelector('.input-validation-type');
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
</script>
```
```jsx:react
import { SlButton, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => {
function handleSubmit(event) {
event.preventDefault();
alert('All fields are valid!');
}
return (
<form onSubmit={handleSubmit}>
<SlInput type="email" label="Email" placeholder="you@example.com" required />
<br />
<SlInput type="url" label="URL" placeholder="https://example.com/" required />
<br />
<SlButton type="submit" variant="primary">
Submit
</SlButton>
</form>
);
};
```
### Custom Error Messages
To create a custom validation error, pass a non-empty string to the `setCustomValidity()` method. This will override any existing validation constraints. The form will not be submitted when a custom validity is set and the browser will show a validation error when the containing form is submitted. To make the input valid again, call `setCustomValidity()` again with an empty string.
```html:preview
<form class="input-validation-custom">
<sl-input label="Type “shoelace”" required></sl-input>
<br />
<sl-button type="submit" variant="primary">Submit</sl-button>
<sl-button type="reset" variant="default">Reset</sl-button>
</form>
<script type="module">
const form = document.querySelector('.input-validation-custom');
const input = form.querySelector('sl-input');
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
input.addEventListener('sl-input', () => {
if (input.value === 'shoelace') {
input.setCustomValidity('');
} else {
input.setCustomValidity("Hey, you're supposed to type 'shoelace' before submitting this!");
}
});
</script>
```
```jsx:react
import { useRef, useState } from 'react';
import { SlButton, SlInput } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const input = useRef(null);
const [value, setValue] = useState('');
function handleInput(event) {
setValue(event.target.value);
if (event.target.value === 'shoelace') {
input.current.setCustomValidity('');
} else {
input.current.setCustomValidity("Hey, you're supposed to type 'shoelace' before submitting this!");
}
}
function handleSubmit(event) {
event.preventDefault();
alert('All fields are valid!');
}
return (
<form onSubmit={handleSubmit}>
<SlInput ref={input} label="Type 'shoelace'" required value={value} onSlInput={handleInput} />
<br />
<SlButton type="submit" variant="primary">
Submit
</SlButton>
</form>
);
};
```
:::tip
Custom validation can be applied to any form control that supports the `setCustomValidity()` method. It is not limited to inputs and textareas.
:::
## Custom Validation Styles
Due to the many ways form controls are used, Shoelace doesn't provide out of the box validation styles for form controls as part of its default theme. Instead, the following attributes will be applied to reflect a control's validity as users interact with it. You can use them to create custom styles for any of the validation states you're interested in.
- `data-required` - the form control is required
- `data-optional` - the form control is optional
- `data-invalid` - the form control is currently invalid
- `data-valid` - the form control is currently valid
- `data-user-invalid` - the form control is currently invalid and the user has interacted with it
- `data-user-valid` - the form control is currently valid and the user has interacted with it
These attributes map to the browser's built-in pseudo classes for validation: [`:required`](https://developer.mozilla.org/en-US/docs/Web/CSS/:required), [`:optional`](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional), [`:invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid), [`:valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:valid), and the proposed [`:user-invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-invalid) and [`:user-valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-valid).
:::tip
In the future, data attributes will be replaced with custom pseudo classes such as `:--valid` and `:--invalid`. Shoelace is using data attributes as a workaround until browsers support custom states through [`ElementInternals.states`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states).
:::
### Styling Invalid Form Controls
You can target validity using any of the aforementioned data attributes, but it's usually preferable to target `data-user-invalid` and `data-user-valid` since they get applied only after a user interaction such as typing or submitting. This prevents empty form controls from appearing invalid immediately, which often results in a poor user experience.
This example demonstrates custom validation styles using `data-user-invalid` and `data-user-valid`. Try Typing in the fields to see how validity changes with user input.
```html:preview
<form class="validity-styles">
<sl-input
name="name"
label="Name"
help-text="What would you like people to call you?"
autocomplete="off"
required
></sl-input>
<sl-select name="animal" label="Favorite Animal" help-text="Select the best option." clearable required>
<sl-option value="birds">Birds</sl-option>
<sl-option value="cats">Cats</sl-option>
<sl-option value="dogs">Dogs</sl-option>
<sl-option value="other">Other</sl-option>
</sl-select>
<sl-checkbox value="accept" required>Accept terms and conditions</sl-checkbox>
<sl-button type="submit" variant="primary">Submit</sl-button>
<sl-button type="reset" variant="default">Reset</sl-button>
</form>
<script type="module">
const form = document.querySelector('.validity-styles');
form.addEventListener('submit', event => {
event.preventDefault();
alert('All fields are valid!');
});
</script>
<style>
.validity-styles sl-input,
.validity-styles sl-select,
.validity-styles sl-checkbox {
display: block;
margin-bottom: var(--sl-spacing-medium);
}
/* user invalid styles */
.validity-styles sl-input[data-user-invalid]::part(base),
.validity-styles sl-select[data-user-invalid]::part(combobox),
.validity-styles sl-checkbox[data-user-invalid]::part(control) {
border-color: var(--sl-color-danger-600);
}
.validity-styles [data-user-invalid]::part(form-control-label),
.validity-styles [data-user-invalid]::part(form-control-help-text),
.validity-styles sl-checkbox[data-user-invalid]::part(label) {
color: var(--sl-color-danger-700);
}
.validity-styles sl-checkbox[data-user-invalid]::part(control) {
outline: none;
}
.validity-styles sl-input:focus-within[data-user-invalid]::part(base),
.validity-styles sl-select:focus-within[data-user-invalid]::part(combobox),
.validity-styles sl-checkbox:focus-within[data-user-invalid]::part(control) {
border-color: var(--sl-color-danger-600);
box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-300);
}
/* User valid styles */
.validity-styles sl-input[data-user-valid]::part(base),
.validity-styles sl-select[data-user-valid]::part(combobox),
.validity-styles sl-checkbox[data-user-valid]::part(control) {
border-color: var(--sl-color-success-600);
}
.validity-styles [data-user-valid]::part(form-control-label),
.validity-styles [data-user-valid]::part(form-control-help-text),
.validity-styles sl-checkbox[data-user-valid]::part(label) {
color: var(--sl-color-success-700);
}
.validity-styles sl-checkbox[data-user-valid]::part(control) {
background-color: var(--sl-color-success-600);
outline: none;
}
.validity-styles sl-input:focus-within[data-user-valid]::part(base),
.validity-styles sl-select:focus-within[data-user-valid]::part(combobox),
.validity-styles sl-checkbox:focus-within[data-user-valid]::part(control) {
border-color: var(--sl-color-success-600);
box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300);
}
</style>
```
## Inline Form Validation
By default, Shoelace form controls use the browser's tooltip-style error messages. No mechanism is provided to show errors inline, as there are too many opinions on how that would work when combined with native form controls and other custom elements. You can, however, implement your own solution using the following technique.
To disable the browser's error messages, you need to cancel the `sl-invalid` event. Then you can apply your own inline validation errors. This example demonstrates a primitive way to do this.
```html:preview
<form class="inline-validation">
<sl-input
name="name"
label="Name"
help-text="What would you like people to call you?"
autocomplete="off"
required
></sl-input>
<div id="name-error" aria-live="polite" hidden></div>
<sl-button type="submit" variant="primary">Submit</sl-button>
<sl-button type="reset" variant="default">Reset</sl-button>
</form>
<script>
const form = document.querySelector('.inline-validation');
const nameError = document.querySelector('#name-error');
// A form control is invalid
form.addEventListener(
'sl-invalid',
event => {
// Suppress the browser's constraint validation message
event.preventDefault();
nameError.textContent = `Error: ${event.target.validationMessage}`;
nameError.hidden = false;
event.target.focus();
},
{ capture: true } // you must use capture since sl-invalid doesn't bubble!
);
// Handle form submit
form.addEventListener('submit', event => {
event.preventDefault();
nameError.hidden = true;
nameError.textContent = '';
setTimeout(() => alert('All fields are valid'), 50);
});
// Handle form reset
form.addEventListener('reset', event => {
nameError.hidden = true;
nameError.textContent = '';
});
</script>
<style>
#name-error {
font-size: var(--sl-input-help-text-font-size-medium);
color: var(--sl-color-danger-700);
}
#name-error ~ sl-button {
margin-top: var(--sl-spacing-medium);
}
.inline-validation sl-input {
display: block;
}
/* user invalid styles */
.inline-validation sl-input[data-user-invalid]::part(base) {
border-color: var(--sl-color-danger-600);
}
.inline-validation [data-user-invalid]::part(form-control-label),
.inline-validation [data-user-invalid]::part(form-control-help-text) {
color: var(--sl-color-danger-700);
}
.inline-validation sl-input:focus-within[data-user-invalid]::part(base) {
border-color: var(--sl-color-danger-600);
box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-300);
}
/* User valid styles */
.inline-validation sl-input[data-user-valid]::part(base) {
border-color: var(--sl-color-success-600);
}
.inline-validation [data-user-valid]::part(form-control-label),
.inline-validation [data-user-valid]::part(form-control-help-text) {
color: var(--sl-color-success-700);
}
.inline-validation sl-input:focus-within[data-user-valid]::part(base) {
border-color: var(--sl-color-success-600);
box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300);
}
</style>
```
:::warning
This example is meant to demonstrate the concept of providing your own error messages inline. It is not intended to scale to more complex forms. Users who want this functionality are encouraged to build a more appropriate validation solution using the techniques shown below. Depending on how you implement this feature, custom error messages may affect the accessibility of your form controls.
:::
## Getting Associated Form Controls
At this time, using [`HTMLFormElement.elements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements) will not return Shoelace form controls because the browser is unaware of their status as custom element form controls. Fortunately, Shoelace provides an `elements()` function that does something very similar. However, instead of returning an [`HTMLFormControlsCollection`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormControlsCollection), it returns an array of HTML and Shoelace form controls in the order they appear in the DOM.
```js
import { getFormControls } from '@shoelace-style/shoelace/dist/utilities/form.js';
const form = document.querySelector('#my-form');
const formControls = getFormControls(form);
console.log(formControls); // e.g. [input, sl-input, ...]
```
:::tip
You probably don't need this function! If you're gathering form data for submission, you probably want to use [Data Serialization](#data-serializing) instead.
:::

175
docs/pages/getting-started/installation.md Normal file
View File

@@ -0,0 +1,175 @@
---
meta:
title: Installation
description: Choose the installation method that works best for you.
---
# Installation
You can load Shoelace via CDN or by installing it locally. If you're using a framework, make sure to check out the pages for [React](/frameworks/react), [Vue](/frameworks/vue), and [Angular](/frameworks/angular) for additional information.
## CDN Installation (Easiest)
<sl-tab-group>
<sl-tab slot="nav" panel="autoloader" active>Autoloader</sl-tab>
<sl-tab slot="nav" panel="traditional">Traditional Loader</sl-tab>
<sl-tab-panel name="autoloader">
The experimental autoloader is the easiest and most efficient way to use Shoelace. A lightweight script watches the DOM for unregistered Shoelace elements and lazy loads them for you — even if they're added dynamically.
While convenient, autoloading may lead to a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/). The linked article describes some ways to alleviate it.
<!-- prettier-ignore -->
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace-autoloader.js"></script>
```
</sl-tab-panel>
<sl-tab-panel name="traditional">
The traditional CDN loader registers all Shoelace elements up front. Note that, if you're only using a handful of components, it will be much more efficient to stick with the autoloader. However, you can also [cherry pick](#cherry-picking) components if you want to load specific ones up front.
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace.js"></script>
```
</sl-tab-panel>
</sl-tab-group>
### Dark Theme
The code above will load the light theme. If you want to use the [dark theme](/getting-started/themes#dark-theme) instead, update the stylesheet as shown below and add `<html class="sl-theme-dark">` to your page.
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css" />
```
### Light & Dark Theme
If you want to load the light or dark theme based on the user's `prefers-color-scheme` setting, use the stylesheets below. The `media` attributes ensure that only the user's preferred theme stylesheet loads and the `onload` attribute sets the appropriate [theme class](/getting-started/themes) on the `<html>` element.
```html
<link
rel="stylesheet"
media="(prefers-color-scheme:light)"
href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css"
/>
<link
rel="stylesheet"
media="(prefers-color-scheme:dark)"
href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css"
onload="document.documentElement.classList.add('sl-theme-dark');"
/>
```
Now you can [start using Shoelace!](/getting-started/usage)
## Local Installation
If you don't want to use the CDN, you can install Shoelace locally with the following command.
```bash
npm install @shoelace-style/shoelace
```
It's up to you to make the source files available to your app. One way to do this is to create a route in your app called `/shoelace` that serves static files from `node_modules/@shoelace-style/shoelace`.
Once you've done that, add the following tags to your page. Make sure to update `href` and `src` so they point to the route you created.
```html
<link rel="stylesheet" href="/shoelace/dist/themes/light.css" />
<script type="module" src="/shoelace/dist/shoelace.js"></script>
```
Alternatively, [you can use a bundler](#bundling).
:::tip
For clarity, the docs will usually show imports from `@shoelace-style/shoelace`. If you're not using a module resolver or bundler, you'll need to adjust these paths to point to the folder Shoelace is in.
:::
## Setting the Base Path
Some components rely on assets (icons, images, etc.) and Shoelace needs to know where they're located. For convenience, Shoelace will try to auto-detect the correct location based on the script you've loaded it from. This assumes assets are colocated with `shoelace.js` or `shoelace-autoloader.js` and will "just work" for most users.
However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Shoelace, you'll need to set the base path. You can do this one of two ways.
```html
<!-- Option 1: the data-shoelace attribute -->
<script src="bundle.js" data-shoelace="/path/to/shoelace/dist"></script>
<!-- Option 2: the setBasePath() method -->
<script src="bundle.js"></script>
<script type="module">
import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
setBasePath('/path/to/shoelace/dist');
</script>
```
:::tip
The library also exports a `getBasePath()` method you can use to reference assets.
:::
## Cherry Picking
Cherry picking can be done from [the CDN](#cdn-installation-easiest) or your [local installation](#local-installation). This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component.
Here's an example that loads only the button component. Again, if you're not using a module resolver, you'll need to adjust the path to point to the folder Shoelace is in.
```html
<link rel="stylesheet" href="/path/to/shoelace/dist/themes/light.css" />
<script type="module" data-shoelace="/path/to/shoelace/dist">
import '@shoelace-style/shoelace/dist/components/button/button.js';
// <sl-button> is ready to use!
</script>
```
You can copy and paste the code to import a component from the "Importing" section of the component's documentation. Note that some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the "Dependencies" section of its docs.
:::warning
Never cherry pick components or utilities from `shoelace.js` as this will cause the browser to load the entire library. Instead, cherry pick from specific modules as shown above.
:::
:::warning
You will see files named `chunk.[hash].js` in the `chunks` directory. Never import these files directly, as they are generated and change from version to version.
:::
## Bundling
Shoelace is distributed as a collection of standard ES modules that [all modern browsers can understand](https://caniuse.com/es6-module). However, importing a lot of modules can result in a lot of HTTP requests and potentially longer load times. Using a CDN can alleviate this, but some users may wish to further optimize their imports with a bundler.
To use Shoelace with a bundler, first install Shoelace along with your bundler of choice.
```bash
npm install @shoelace-style/shoelace
```
Now it's time to configure your bundler. Configurations vary for each tool, but here are some examples to help you get started.
- [Example webpack config](https://github.com/shoelace-style/webpack-example/blob/master/webpack.config.js)
- [Example Rollup config](https://github.com/shoelace-style/rollup-example/blob/master/rollup.config.js)
Once your bundler is configured, you'll be able to import Shoelace components and utilities.
```js
import '@shoelace-style/shoelace/dist/themes/light.css';
import '@shoelace-style/shoelace/dist/components/button/button.js';
import '@shoelace-style/shoelace/dist/components/icon/icon.js';
import '@shoelace-style/shoelace/dist/components/input/input.js';
import '@shoelace-style/shoelace/dist/components/rating/rating.js';
import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
// Set the base path to the folder you copied Shoelace's assets to
setBasePath('/path/to/shoelace/dist');
// <sl-button>, <sl-icon>, <sl-input>, and <sl-rating> are ready to use!
```
:::warning
Component modules include side effects for registration purposes. Because of this, importing directly from `@shoelace-style/shoelace` may result in a larger bundle size than necessary. For optimal tree shaking, always cherry pick, i.e. import components and utilities from their respective files, as shown above.
:::

138
docs/pages/getting-started/localization.md Normal file
View File

@@ -0,0 +1,138 @@
---
meta:
title: Localization
description: Discover how to localize Shoelace with minimal effort.
---
# Localization
Components can be localized by importing the appropriate translation file and setting the desired [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) and/or [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) on the `<html>` element. Here's an example that renders Shoelace components in Spanish.
```html
<html lang="es">
<head>
<script type="module" src="/path/to/shoelace/dist/translations/es.js"></script>
</head>
<body>
...
</body>
</html>
```
Through the magic of a mutation observer, changing the `lang` attribute will automatically update all localized components to use the new locale.
## Available Translations
Shoelace ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation. To see a list of all available translations in the latest version, [refer to this directory](https://github.com/shoelace-style/shoelace/tree/current/src/translations).
The location of translations depends on how you're consuming Shoelace.
- If you're using the CDN, [import them from the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace?path=dist%2Ftranslations)
- If you're using a bundler, import them from `@shoelace-style/shoelace/dist/translations/[lang].js`
You do not need to load translations up front. You can import them dynamically even after updating the `lang` attribute. Once a translation is registered, localized components will update automatically.
```js
// Same as setting <html lang="de">
document.documentElement.lang = 'de';
// Import the translation
import('/path/to/shoelace/dist/translations/de.js');
```
### Translation Resolution
The locale set by `<html lang="...">` is the default locale for the document. If a country code is provided, e.g. `es-PE` for Peruvian Spanish, the localization library will resolve it like this:
1. Look for `es-PE`
2. Look for `es`
3. Fall back to `en`
Shoelace uses English as a fallback to provide a better experience than rendering nothing or throwing an error.
### Submitting New Translations or Improvements
To contribute new translations or improvements to existing translations, please submit a pull request on GitHub. Translations are located in [`src/translations`](https://github.com/shoelace-style/shoelace/blob/next/src/translations) and can be edited directly on GitHub if you don't want to clone the repo locally.
Regional translations are welcome! For example, if a German translation (`de`) exists it's perfectly acceptable to submit a German (Switzerland) (`de-CH`) translation.
If you have any questions, please start a [discussion](https://github.com/shoelace-style/shoelace/discussions) or ask in the [community chat](https://discord.gg/mg8f26C).
:::tip
Shoelace provides a localization mechanism for component internals. This is not designed to be used as localization tool for your entire application. You should use a more appropriate tool such as [i18next](https://www.i18next.com/) if you need to localize content in your app.
:::
## Multiple Locales Per Page
You can use a different locale for an individual component by setting its `lang` and/or `dir` attributes. Here's a contrived example to demonstrate.
```html
<html lang="es">
...
<body>
<sl-button><!-- Spanish --></sl-button>
<sl-button lang="ru"><!-- Russian --></sl-button>
</body>
</html>
```
For performance reasons, the `lang` and `dir` attributes must be on the component itself, not on an ancestor element.
```html
<html lang="es">
...
<body>
<div lang="ru">
<sl-button><!-- still in Spanish --></sl-button>
</div>
</body>
</html>
```
This limitation exists because there's no efficient way to determine the current locale of a given element in a DOM tree. I consider this a gap in the platform and [I've proposed a couple properties](https://github.com/whatwg/html/issues/7039) to make this possible.
## Creating Your Own Translations
You can provide your own translations if you have specific needs or if you don't want to wait for a translation to land upstream. The easiest way to do this is to copy `src/translations/en.ts` into your own project and translate the terms inside. When your translation is done, you can import it and use it just like a built-in translation.
Let's create a Spanish translation as an example. The following assumes you're using TypeScript, but you can also create translations with regular JavaScript.
```js
import { registerTranslation } from '@shoelace-style/shoelace/dist/utilities/localize';
import type { Translation } from '@shoelace-style/shoelace/dist/utilities/localize';
const translation: Translation = {
$code: 'es',
$name: 'Español',
$dir: 'ltr',
term1: '...',
term2: '...',
...
};
registerTranslation(translation);
export default translation;
```
Once your translation has been compiled to JavaScript, import it and activate it like this.
```html
<html lang="es">
<head>
<script type="module" src="/path/to/es.js"></script>
</head>
<body>
...
</body>
</html>
```
:::tip
If your translation isn't working, make sure you're using the same localize module when importing `registerTranslation`. If you're using a different module, your translation won't be recognized.
:::

149
docs/pages/getting-started/themes.md Normal file
View File

@@ -0,0 +1,149 @@
---
meta:
title: Themes
description: Everything you need to know about theming Shoelace.
---
# Themes
Shoelace is designed to be highly customizable through pure CSS. Out of the box, you can choose from a light or dark theme. Alternatively, you can design your own theme.
A theme is nothing more than a stylesheet that uses the Shoelace API to define design tokens and apply custom styles to components. To create a theme, you will need a decent understanding of CSS, including [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and the [`::part` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).
:::tip
For component developers, built-in themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `dist/themes/*.styles.js`.
:::
## Theme Basics
All themes are scoped to classes using the `sl-theme-{name}` convention, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use `sl-theme-light` and `sl-theme-dark`, respectively. A custom theme called "Purple Power", for example, would use a class called `sl-theme-purple-power`
All selectors must be scoped to the theme's class to ensure interoperability with other themes. You should also scope them to `:host` so they can be imported and applied to custom element shadow roots.
```css
:host,
.sl-theme-purple-power {
/* ... */
}
```
### Activating Themes
To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the built-in dark theme.
```html
<html class="sl-theme-dark">
<head>
<link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css" />
</head>
<body>
...
</body>
</html>
```
:::tip
There is one exception to this rule — the light theme _does not_ need to be activated. For convenience, the light theme is scoped to `:root` and will be activated by default when imported.
:::
### Using Multiple Themes
You can activate themes on various containers throughout the page. This example uses the light theme with a dark-themed sidebar.
```html
<html>
<head>
<link rel="stylesheet" href="path/to/shoelace/dist/themes/light.css" />
<link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css" />
</head>
<body>
<nav class="sl-theme-dark">
<!-- dark-themed sidebar -->
</nav>
<!-- light-themed content -->
</body>
</html>
```
It's for this reason that themes must be scoped to specific classes.
## Creating Themes
There are two ways to create themes. The easiest way is to customize a built-in theme. The advanced way is to create a new theme from scratch. Which method you choose depends on your project's requirements and the amount of effort you're willing to commit to.
### Customizing a Built-in Theme
The easiest way to customize Shoelace is to override one of the built-in themes. You can do this by importing the light or dark theme as-is, then creating a separate stylesheet that overrides [design tokens](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the built-in theme.
If you're customizing the light theme, you should scope your styles to the following selectors.
```css
:root,
:host,
.sl-theme-light {
/* your custom styles here */
}
```
If you're customizing the dark theme, you should scope your styles to the following selectors.
```css
:host,
.sl-theme-dark {
/* your custom styles here */
}
```
By customizing a built-in theme, you'll maintain a smaller stylesheet containing only the changes you've made. Contrast this to [creating a new theme](#creating-a-new-theme), where you need to explicitly define every design token required by the library. This approach is more "future-proof," as new design tokens that emerge in subsequent versions of Shoelace will be accounted for by the built-in theme.
While this approach is easier to maintain, the drawback is that your theme can't be activated independently — it's tied to the built-in theme you're extending.
### Creating a New Theme
Creating a new theme is more of an undertaking than [customizing an existing one](#customizing-a-built-in-theme). At a minimum, you must implement all of the required design tokens. The easiest way to do this is by "forking" one of the built-in themes and modifying it from there.
Start by changing the selector to match your theme's name. Assuming your new theme is called "Purple Power", your theme should be scoped like this.
```css
:host,
.sl-theme-purple-power {
/* your custom styles here */
}
```
By creating a new theme, you won't be relying on a built-in theme as a foundation. Because the theme is decoupled from the built-ins, you can activate it independently as an alternative to the built-ins. This is the recommended approach if you're looking to open source your theme for others to use.
You will, however, need to maintain your theme more carefully, as new versions of Shoelace may introduce new design tokens that your theme won't have accounted for. Because of this, it's recommended that you clearly specify which version(s) of Shoelace your theme is designed to work with and keep it up to date as new versions of Shoelace are released.
## Dark Theme
The built-in dark theme uses an inverted color scale so, if you're using design tokens as intended, you'll get dark mode for free. While this isn't the same as a professionally curated dark theme, it provides an excellent baseline for one and you're encouraged to customize it depending on your needs.
The dark theme works by taking the light theme's [color tokens](/tokens/color) and "flipping" the scale so 100 becomes 900, 200 becomes 800, 300 becomes 700, etc. Next, the luminance of each primitive was fine-tuned to avoid true black, which is often undesirable in dark themes, and provide a richer experience. The result is a custom dark palette that complements the light theme and makes it easy to offer light and dark modes with minimal effort.
To install the dark theme, add the following to the `<head>` section of your page.
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css" />
```
To activate the theme, apply the `sl-theme-dark` class to the `<html>` element.
```html
<html class="sl-theme-dark">
...
</html>
```
### Detecting the User's Color Scheme Preference
Shoelace doesn't try to auto-detect the user's light/dark mode preference. This should be done at the application level. As a best practice, to provide a dark theme in your app, you should:
- Check for [`prefers-color-scheme`](https://stackoverflow.com/a/57795495/567486) and use its value by default
- Allow the user to override the setting in your app
- Remember the user's preference and restore it on subsequent logins
Shoelace avoids using the `prefers-color-scheme` media query because not all apps support dark mode, and it would break things for the ones that don't.

215
docs/pages/getting-started/usage.md Normal file
View File

@@ -0,0 +1,215 @@
---
meta:
title: Usage
description: Learn more about using custom elements.
---
# Usage
Shoelace components are just regular HTML elements, or [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) to be precise. You can use them like any other element. Each component has detailed documentation that describes its full API, including properties, events, methods, and more.
If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them.
## Attributes & Properties
Many components have properties that can be set using attributes. For example, buttons accept a `size` attribute that maps to the `size` property which dictates the button's size.
```html
<sl-button size="small">Click me</sl-button>
```
Some properties are boolean, so they only have true/false values. To activate a boolean property, add the corresponding attribute without a value.
```html
<sl-button disabled>Click me</sl-button>
```
In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This must be done with JavaScript.
```html
<sl-color-picker></sl-color-picker>
<script>
const colorPicker = document.querySelector('sl-color-picker');
colorPicker.swatches = ['red', 'orange', 'yellow', 'green', 'blue', 'purple'];
</script>
```
Refer to a component's documentation for a complete list of its properties.
## Events
You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. However, it's important to note that many events emitted within a component's shadow root will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in, for example, multiple `click` handlers executing even if the user clicks just once. Furthermore, `event.target` will point to the host element, making things even more confusing.
As a result, you should almost always listen for custom events instead. For example, instead of listening to `click` to determine when an `<sl-checkbox>` gets toggled, listen to `sl-change`.
```html
<sl-checkbox>Check me</sl-checkbox>
<script>
const checkbox = document.querySelector('sl-checkbox');
checkbox.addEventListener('sl-change', event => {
console.log(event.target.checked ? 'checked' : 'not checked');
});
</script>
```
All custom events are prefixed with `sl-` to prevent collisions with standard events and other libraries. Refer to a component's documentation for a complete list of its custom events.
## Methods
Some components have methods you can call to trigger various behaviors. For example, you can set focus on a Shoelace input using the `focus()` method.
```html
<sl-input></sl-input>
<script>
const input = document.querySelector('sl-input');
input.focus();
</script>
```
Refer to a component's documentation for a complete list of its methods and their arguments.
## Slots
Many components use slots to accept content inside of them. The most common slot is the _default_ slot, which includes any content inside the component that doesn't have a `slot` attribute.
For example, a button's default slot is used to populate its label.
```html
<sl-button>Click me</sl-button>
```
Some components also have _named_ slots. A named slot can be populated by adding a child element with the appropriate `slot` attribute. Notice how the icon below has the `slot="prefix"` attribute? This tells the component to place the icon into its `prefix` slot.
```html
<sl-button>
<sl-icon slot="prefix" name="gear"></sl-icon>
Settings
</sl-button>
```
The location of a named slot doesn't matter. You can put it anywhere inside the component and the browser will move it to the right place automatically!
Refer to a component's documentation for a complete list of available slots.
## Don't Use Self-closing Tags
Custom elements cannot have self-closing tags. Similar to `<script>` and `<textarea>`, you must always include the full closing tag.
```html
<!-- Don't do this -->
<sl-input />
<!-- Always do this -->
<sl-input></sl-input>
```
## Differences from Native Elements
You might expect similarly named elements to share the same API as native HTML elements. This is not always the case. Shoelace components **are not** designed to be one-to-one replacements for their HTML counterparts.
For example, `<button>` and `<sl-button>` both have a `type` attribute, but it does different things. The former controls whether the button submits a form and the latter controls the button's appearance.
:::tip
**Don't make assumptions about a component's API!** To prevent unexpected behaviors, please take the time to review the documentation and make sure you understand what each attribute, property, method, and event is intended to do.
:::
## Waiting for Components to Load
Web components are registered with JavaScript, so depending on how and when you load Shoelace, you may notice a [Flash of Undefined Custom Elements (FOUCE)](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/) when the page loads. There are a couple ways to prevent this, both of which are described in the linked article.
One option is to use the [`:defined`](https://developer.mozilla.org/en-US/docs/Web/CSS/:defined) CSS pseudo-class to "hide" custom elements that haven't been registered yet. You can scope it to specific tags or you can hide all undefined custom elements as shown below.
```css
:not(:defined) {
visibility: hidden;
}
```
As soon as a custom element is registered, it will immediately appear with all of its styles, effectively eliminating FOUCE. Note the use of `visibility: hidden` instead of `display: none` to reduce shifting as elements are registered. The drawback to this approach is that custom elements can potentially appear one by one instead of all at the same time.
Another option is to use [`customElements.whenDefined()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined), which returns a promise that resolves when the specified element gets registered. You'll probably want to use it with [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) in case an element fails to load for some reason.
A clever way to use this method is to hide the `<body>` with `opacity: 0` and add a class that fades it in as soon as all your custom elements are defined.
```html
<style>
body {
opacity: 0;
}
body.ready {
opacity: 1;
transition: 0.25s opacity;
}
</style>
<script type="module">
await Promise.allSettled([
customElements.whenDefined('sl-button'),
customElements.whenDefined('sl-card'),
customElements.whenDefined('sl-rating')
]);
// Button, card, and rating are registered now! Add
// the `ready` class so the UI fades in.
document.body.classList.add('ready');
</script>
```
## Component Rendering and Updating
Shoelace components are built with [Lit](https://lit.dev/), a tiny library that makes authoring custom elements easier, more maintainable, and a lot of fun! As a Shoelace user, here is some helpful information about rendering and updating you should probably be aware of.
To optimize performance and reduce re-renders, Lit batches component updates. This means changing multiple attributes or properties at the same time will result in just a single re-render. In most cases, this isn't an issue, but there may be times you'll need to wait for the component to update before continuing.
Consider this example. We're going to change the `checked` property of the checkbox and observe its corresponding `checked` attribute, which happens to reflect.
```js
const checkbox = document.querySelector('sl-checkbox');
checkbox.checked = true;
console.log(checkbox.hasAttribute('checked')); // false
```
Most developers will expect this to be `true` instead of `false`, but the component hasn't had a chance to re-render yet so the attribute doesn't exist when `hasAttribute()` is called. Since changes are batched, we need to wait for the update before proceeding. This can be done using the `updateComplete` property, which is available on all Lit-based components.
```js
const checkbox = document.querySelector('sl-checkbox');
checkbox.checked = true;
checkbox.updateComplete.then(() => {
console.log(checkbox.hasAttribute('checked')); // true
});
```
This time we see an empty string, which means the boolean attribute is now present!
:::tip
Avoid using `setTimeout()` or `requestAnimationFrame()` in situations like this. They might work, but it's far more reliable to use `updateComplete` instead.
:::
## Code Completion
### VS Code
Shoelace ships with a file called `vscode.html-custom-data.json` that can be used to describe it's custom elements to Visual Studio Code. This enables code completion for Shoelace components (also known as "code hinting" or "IntelliSense"). To enable it, you need to tell VS Code where the file is.
1. [Install Shoelace locally](/getting-started/installation#local-installation)
2. If it doesn't already exist, create a folder called `.vscode` at the root of your project
3. If it doesn't already exist, create a file inside that folder called `settings.json`
4. Add the following to the file
```js
{
"html.customData": ["./node_modules/@shoelace-style/shoelace/dist/vscode.html-custom-data.json"]
}
```
If `settings.json` already exists, simply add the above line to the root of the object. Note that you may need to restart VS Code for the changes to take affect.
### Other Editors
Most popular editors support custom code completion with a bit of configuration. Please [submit a feature request](https://github.com/shoelace-style/shoelace/issues/new/choose) for your editor of choice. PRs are also welcome!

140
docs/pages/index.md Normal file
View File

@@ -0,0 +1,140 @@
---
meta:
title: 'Shoelace: A forward-thinking library of web components.'
description: Hand-crafted custom elements for any occasion.
toc: false
---
<div class="splash">
<div class="splash-start">
<img class="splash-logo" src="/assets/images/wordmark.svg" alt="Shoelace">
# <sl-visually-hidden>Shoelace:</sl-visually-hidden> A forward-thinking library of web components.
- Works with all frameworks 🧩
- Works with CDNs 🚛
- Fully customizable with CSS 🎨
- Includes a dark theme 🌛
- Built with accessibility in mind ♿️
- First-class [React support](/frameworks/react) ⚛️
- Built-in localization 💬
- Open source 😸
Designed in New Hampshire by [Cory LaViska](https://twitter.com/claviska).
</div>
<div class="splash-end">
<img class="splash-image" src="/assets/images/undraw-content-team.svg" alt="Cartoon of people assembling components while standing on a giant laptop.">
</div>
</div>
[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@shoelace-style/shoelace/badge)](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace)
[![npm](https://img.shields.io/npm/dw/@shoelace-style/shoelace?label=npm&style=flat-square)](https://www.npmjs.com/package/@shoelace-style/shoelace)
[![License](https://img.shields.io/badge/license-MIT-232323.svg?style=flat-square)](https://github.com/shoelace-style/shoelace/blob/next/LICENSE.md)<br>
[![Discord](https://img.shields.io/badge/Discord-Join%20the%20chat-5965f2.svg?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/mg8f26C)
[![Twitter](https://img.shields.io/badge/Twitter-Follow-00acee.svg?style=flat-square&logo=twitter&logoColor=white)](https://twitter.com/shoelace_style)
[![Sponsor](https://img.shields.io/badge/GitHub-Code-232323.svg?style=flat-square&logo=github&logoColor=white)](https://github.com/shoelace-style/shoelace)
## Quick Start
Add the following code to your page.
<!-- prettier-ignore -->
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace-autoloader.js"></script>
```
Now you have access to all of Shoelace's components! Try adding a button:
```html:preview:expanded:no-codepen
<sl-button>Click me</sl-button>
```
:::tip
This will activate Shoelace's experimental autoloader, which registers components on the fly as you use them. To learn more about it, or for other ways to install Shoelace, refer to the [installation instructions](getting-started/installation).
:::
## New to Web Components?
**TL;DR** – we finally have a way to create [our own HTML elements](https://html.spec.whatwg.org/multipage/custom-elements.html) and use them in any framework we want!
Thanks to the popularity of frameworks such as Angular, Vue, and React, component-driven development has become a part of our every day lives. Components help us encapsulate styles and behaviors into reusable building blocks. They make a lot of sense in terms of design, development, and testing.
Unfortunately, _framework-specific_ components fail us in a number of ways:
- You can only use them in the framework they're designed for 🔒
- Their lifespan is limited to that of the framework's ⏳
- New frameworks/versions can lead to breaking changes, requiring substantial effort to update components 😭
Web components solve these problems. They're [supported by all modern browsers](https://caniuse.com/#feat=custom-elementsv1), they're framework-agnostic, and they're [part of the standard](https://developer.mozilla.org/en-US/docs/Web/Web_Components), so we know they'll be supported for many years to come.
This is the technology that Shoelace is built on.
## What Problem Does This Solve?
Shoelace provides a collection of professionally designed, highly customizable UI components built on a framework agnostic technology. Why spend hundreds of hours (or more) building a design system from scratch? Why make a component library that only works with one framework?
With Shoelace, you can:
- Start building things faster (no need to roll your own buttons)
- Build multiple apps with different frameworks that all share the same UI components
- Fully customize components to match your existing designs
- Incrementally adopt components as needed (no need to ditch your framework)
- Upgrade or switch frameworks without rebuilding foundational components
If your organization is looking to build a design system, [Shoelace will save you thousands of dollars](https://medium.com/eightshapes-llc/and-you-thought-buttons-were-easy-26eb5b5c1871).\* All the foundational components you need are right here, ready to be customized for your brand. And since it's built on web standards, browsers will continue to support it for many years to come.
Whether you use Shoelace as a starting point for your organization's design system or for a fun personal project, there's no limit to what you can do with it.
<small>\*Please consider giving back some of what you save by [supporting this project with a sponsorship](https://github.com/sponsors/claviska).</small>
## Browser Support
Shoelace is tested in the latest two versions of the following browsers.
<img src="/assets/images/chrome.png" alt="Chrome" width="64" height="64">
<img src="/assets/images/edge.png" alt="Edge" width="64" height="64">
<img src="/assets/images/firefox.png" alt="Firefox" width="64" height="64">
<img src="/assets/images/opera.png" alt="Opera" width="64" height="64">
<img src="/assets/images/safari.png" alt="Safari" width="64" height="64">
Critical bug fixes in earlier versions will be addressed based on their severity and impact.
If you need to support IE11 or pre-Chromium Edge, this library isn't for you. Although web components can (to some degree) be polyfilled for legacy browsers, supporting them is outside the scope of this project. If you're using Shoelace in such a browser, you're gonna have a bad time. ⛷
## License
Shoelace is designed in New Hampshire by [Cory LaViska](https://twitter.com/claviska). It's available under the terms of the MIT license.
Designing, developing, and supporting this library requires a lot of time, effort, and skill. If you're using this software to make a profit, I respectfully ask that you help [fund its development](https://github.com/sponsors/claviska) by becoming a sponsor.
👇 Your support is very much appreciated! 👇
<sl-button class="repo-button repo-button--sponsor" href="https://github.com/sponsors/claviska" target="_blank">
<sl-icon slot="prefix" name="heart"></sl-icon> Become a sponsor
</sl-button>
<sl-button class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace/stargazers" target="_blank">
<sl-icon slot="prefix" name="github"></sl-icon> Star
</sl-button>
<sl-button class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
<sl-icon slot="prefix" name="twitter"></sl-icon> Follow
</sl-button>
## Attribution
Special thanks to the following projects and individuals that help make Shoelace possible.
- Components are built with [Lit](https://lit.dev/)
- Component metadata is generated by the [Custom Elements Manifest Analyzer](https://github.com/open-wc/custom-elements-manifest)
- Documentation is powered by [11ty](https://www.11ty.dev/)
- CDN services are provided by [jsDelivr](https://www.jsdelivr.com/)
- Color primitives are inspired by [Tailwind](https://tailwindcss.com/)
- Icons are courtesy of [Bootstrap Icons](https://icons.getbootstrap.com/)
- The homepage illustration is courtesy of [unDraw](https://undraw.co/)
- Positioning of dropdowns, tooltips, et al is handled by [Floating UI](https://floating-ui.com/)
- Animations are courtesy of [animate.css](https://animate.style/)
- Search is powered by [Lunr](https://lunrjs.com/)
- The Shoelace logo was designed with a single shoelace by [Adam K Olson](https://twitter.com/adamkolson)

24
docs/pages/resources/accessibility.md Normal file
View File

@@ -0,0 +1,24 @@
---
meta:
title: Accessibility Commitment
description: Shoelace recognizes the need for all users to have undeterred access to the websites and applications that are created with it.
---
# Accessibility Commitment
Shoelace recognizes the need for all users, regardless of ability and device, to have undeterred access to the websites and applications that are created with it. This is an important goal of the project.
Oftentimes, people will ask “is Shoelace accessible?” I’m reluctant to answer because accessibility isn’t binary — there’s no simple “yes” or “no” response to provide. What seems accessible to a sighted user might be completely inaccessible to a non-sighted user. And even if you optimize for various screen readers, you still have to account for low-level vision, color blindness, hearing impairments, mobility impairments, and more.
Accessibility is something you have to continuously strive for. No individual contributor — or perhaps even an entire team — can claim their software is 100% accessible because of the sheer diversity of abilities, devices, assistive technologies, and individual use cases.
Furthermore, accessibility doesn’t stop at the component level. Using accessible building blocks doesn’t magically make the rest of your webpage or application compliant. There is no library or overlay that will make your software “fully accessible” without putting in the effort. It’s also worth noting that web components are still somewhat bleeding edge, so browsers, assistive devices, and [even specifications](https://wicg.github.io/aom/spec/) are still evolving to help improve accessibility on the web platform.
My commitment to Shoelace users is this: Everything I develop will be built with accessibility in mind. I will test and improve every component to the best of my ability and knowledge. I will work around upstream issues, such as browser bugs and limitations, to the best of my ability and within reason.
I’m fully aware that I may not get it right every time for every user, so I invite the community to participate in this ongoing effort by submitting [issues](https://github.com/shoelace-style/shoelace/issues?q=is%3Aissue+is%3Aopen+label%3Aa11y), [pull requests](https://github.com/shoelace-style/shoelace/pulls?q=is%3Aopen+is%3Apr+label%3Aa11y), and [discussions](https://github.com/shoelace-style/shoelace/discussions). Many accessibility improvements have already been made thanks to contributors submitting code, feedback, and suggestions.
This is the path forward. Together, we will continue to make Shoelace accessible to as many users as possible.
— Cory LaViska<br>
_Creator of Shoelace_

1539
docs/pages/resources/changelog.md Normal file
View File

File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More