diff --git a/docs/assets/plugins/code-block/code-block.js b/docs/assets/plugins/code-block/code-block.js index 34afb5e97..82318e495 100644 --- a/docs/assets/plugins/code-block/code-block.js +++ b/docs/assets/plugins/code-block/code-block.js @@ -239,10 +239,6 @@ .querySelector('.code-block__button--react') ?.classList.toggle('code-block__button--selected', flavor === 'react'); }); - - // Expand the code block - codeBlock.classList.add('code-block--expanded'); - codeBlock.querySelector('.code-block__toggle').setAttribute('aria-expanded', 'true'); }); // Expand and collapse code blocks @@ -319,6 +315,7 @@ '\n' + 'body {\n' + ' font: 16px sans-serif;\n' + + ' padding: 1rem;\n' + '}'; // Docs: https://blog.codepen.io/documentation/prefill/ diff --git a/docs/components/alert.md b/docs/components/alert.md index b8d8fb8ba..8d97b0cce 100644 --- a/docs/components/alert.md +++ b/docs/components/alert.md @@ -11,6 +11,17 @@ Alerts are used to display important messages either inline or as toast notifica ``` +```jsx react +import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + + This is a standard alert. You can customize its content and even the icon. + +); +``` + ?> Alerts will not be visible if the `open` attribute is not present. ## Examples @@ -59,6 +70,52 @@ Set the `type` attribute to change the alert's type. ``` +```jsx react +import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + This is super informative
+ You can tell by how pretty the alert is. + + +
+ + + + Your changes have been saved
+ You can safely exit the app now. + + +
+ + + + Your settings have been updated
+ Settings will take affect on next login. + + +
+ + + + Your session has ended
+ Please login again to continue. + + +
+ + + + Your account has been deleted
+ We're very sorry to see you go! + + +); +``` + ### Closable Add the `closable` attribute to show a close button that will hide the alert. @@ -77,6 +134,31 @@ Add the `closable` attribute to show a close button that will hide the alert. ``` +```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 ( + + + You can close this alert any time! + + ); +}; +``` + ### Without Icons Icons are optional. Simply omit the `icon` slot if you don't want them. @@ -87,6 +169,16 @@ Icons are optional. Simply omit the `icon` slot if you don't want them. ``` +```jsx react +import { SlAlert } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Nothing fancy here, just a simple alert. + +); +``` + ### 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. @@ -116,6 +208,46 @@ Set the `duration` attribute to automatically hide an alert after a period of ti ``` +```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 ( + <> +
+ setOpen(true)}>Show Alert + + setOpen(false)} + > + + This alert will automatically hide itself after three seconds, unless you interact with it. + +
+ + + + ); +}; +``` + ### 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. @@ -173,6 +305,81 @@ You should always use the `closable` attribute so users can dismiss the notifica ``` +```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 ( + <> + primary.current.toast()}> + Primary + + + success.current.toast()}> + Success + + + neutral.current.toast()}> + Neutral + + + warning.current.toast()}> + Warning + + + danger.current.toast()}> + Danger + + + + + This is super informative
+ You can tell by how pretty the alert is. + + + + + Your changes have been saved
+ You can safely exit the app now. + + + + + Your settings have been updated
+ Settings will take affect on next login. + + + + + Your session has ended
+ Please login again to continue. + + + + + Your account has been deleted
+ We're very sorry to see you go! + + + ); +}; +``` + ### 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. diff --git a/docs/components/animated-image.md b/docs/components/animated-image.md index f4dd46058..917689bd5 100644 --- a/docs/components/animated-image.md +++ b/docs/components/animated-image.md @@ -6,11 +6,24 @@ A component for displaying animated GIFs and WEBPs that play and pause on intera ```html preview ``` +```jsx react +import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + +?> This component uses `` 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 @@ -19,31 +32,54 @@ Both GIF and WEBP images are supported. ```html preview ``` +```jsx react +import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### Setting a Width and Height To set a custom size, apply a width and/or height to the host element. ```html preview ``` +```jsx react +import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### 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 @@ -60,4 +96,31 @@ You can change the appearance and location of the control box by targeting the ` ``` +```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; + color: white; + } +`; + +const App = () => ( + <> + + + + +); +``` + [component-metadata:sl-animated-image] diff --git a/docs/components/avatar.md b/docs/components/avatar.md index 0ec63dfdb..43e2efc5c 100644 --- a/docs/components/avatar.md +++ b/docs/components/avatar.md @@ -8,6 +8,14 @@ Avatars are used to represent a person or object. ``` +```jsx react +import { SlAvatar } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + Button +); +``` + ## Examples ### Images @@ -21,6 +29,17 @@ To use an image for the avatar, set the `image` and `alt` attributes. This will > ``` +```jsx react +import { SlAvatar } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### Initials When you don't have an image to use, you can set the `initials` attribute to show something more personalized than an icon. @@ -29,6 +48,14 @@ When you don't have an image to use, you can set the `initials` attribute to sho ``` +```jsx react +import { SlAvatar } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### 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. @@ -47,18 +74,47 @@ When no image or initials are set, an icon will be shown. The default avatar sho ``` +```jsx react +import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + + + + + + + + + + +); +``` + ### Shapes Avatars can be shaped using the `shape` attribute. ```html preview - - ``` +```jsx react +import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + + +); +``` ### Avatar Groups @@ -83,4 +139,31 @@ You can group avatars with a few lines of CSS. ``` +```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 rgb(var(--sl-color-neutral-0)); + } +`; + +const App = () => ( + <> +
+ + + + +
+ + + +); +``` + [component-metadata:sl-avatar] diff --git a/docs/components/badge.md b/docs/components/badge.md index 87f113a40..015f15781 100644 --- a/docs/components/badge.md +++ b/docs/components/badge.md @@ -8,6 +8,14 @@ Badges are used to draw attention and display statuses or counts. Badge ``` +```jsx react +import { SlBadge } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + Badge +); +``` + ## Examples ### Types @@ -22,6 +30,20 @@ Set the `type` attribute to change the badge's type. Danger ``` +```jsx react +import { SlBadge } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Primary + Success + Neutral + Warning + Danger + +); +``` + ### Pill Badges Use the `pill` attribute to give badges rounded edges. @@ -34,6 +56,20 @@ Use the `pill` attribute to give badges rounded edges. Danger ``` +```jsx react +import { SlBadge } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Primary + Success + Neutral + Warning + Danger + +); +``` + ### Pulsating Badges Use the `pulse` attribute to draw attention to the badge with a subtle animation. @@ -54,6 +90,30 @@ Use the `pulse` attribute to draw attention to the badge with a subtle animation ``` +```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 = () => ( + <> +
+ 1 + 1 + 1 + 1 + 1 +
+ + + +); +``` + ### 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. @@ -75,6 +135,29 @@ One of the most common use cases for badges is attaching them to buttons. To mak ``` +```jsx react +import { SlBadge, SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + Requests + 30 + + + + Warnings + 8 + + + + Errors + 6 + + +); +``` + ### With Menu Items When including badges in menu items, use the `suffix` slot to make sure they're aligned correctly. @@ -87,4 +170,22 @@ When including badges in menu items, use the `suffix` slot to make sure they're ``` +```jsx react +import { SlBadge, SlButton, SlMenu, SlMenuItem, SlMenuLabel } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Messages + Comments 4 + Replies 12 + +); +``` + [component-metadata:sl-badge] diff --git a/docs/components/breadcrumb-item.md b/docs/components/breadcrumb-item.md index 43f1ec2ea..308e069c2 100644 --- a/docs/components/breadcrumb-item.md +++ b/docs/components/breadcrumb-item.md @@ -15,6 +15,21 @@ Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to repres ``` +```jsx react +import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + + + Home + + Clothing + Shirts + +); +``` + ?> Additional demonstrations can be found in the [breadcrumb examples](/components/breadcrumb). [component-metadata:sl-breadcrumb-item] diff --git a/docs/components/breadcrumb.md b/docs/components/breadcrumb.md index defd68581..4a8f53979 100644 --- a/docs/components/breadcrumb.md +++ b/docs/components/breadcrumb.md @@ -15,6 +15,19 @@ Breadcrumbs are usually placed before a page's main content with the current pag ``` +```jsx react +import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Catalog + Clothing + Women's + Shirts & Tops + +); +``` + ## Examples ### Breadcrumb Links @@ -43,6 +56,30 @@ For websites, you'll probably want to use links instead. You can make any breadc ``` +```jsx react +import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + + Homepage + + + + Our Services + + + + Digital Media + + + + Web Design + + +); +``` + ### 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. @@ -74,6 +111,40 @@ Use the `separator` slot to change the separator that goes between breadcrumb it ``` +```jsx react +import '@shoelace-style/shoelace/dist/components/icon/icon.js'; +import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + First + Second + Third + + +
+ + + + First + Second + Third + + +
+ + + / + First + Second + Third + + +); +``` + ### Prefixes Use the `prefix` slot to add content before any breadcrumb item. @@ -89,6 +160,21 @@ Use the `prefix` slot to add content before any breadcrumb item. ``` +```jsx react +import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + + + Home + + Articles + Traveling + +); +``` + ### Suffixes Use the `suffix` slot to add content after any breadcrumb item. @@ -104,6 +190,21 @@ Use the `suffix` slot to add content after any breadcrumb item. ``` +```jsx react +import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Documents + Policies + + Security + + + +); +``` + ### With Dropdowns Dropdown menus can be placed in a prefix or suffix slot to provide additional options. @@ -129,4 +230,37 @@ Dropdown menus can be placed in a prefix or suffix slot to provide additional op ``` +```jsx react +import { + SlBreadcrumb, + SlBreadcrumbItem, + SlButton, + SlDropdown, + SlIcon, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Homepage + Our Services + Digital Media + + Web Design + + + + + + Web Design + Web Development + Marketing + + + + +); +``` + [component-metadata:sl-breadcrumb] diff --git a/docs/components/button-group.md b/docs/components/button-group.md index b7b1d92e7..c285494a0 100644 --- a/docs/components/button-group.md +++ b/docs/components/button-group.md @@ -12,6 +12,18 @@ Button groups can be used to group related buttons into sections. ``` +```jsx react +import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Left + Center + Right + +); +``` + ## Examples ### Button Sizes @@ -42,6 +54,36 @@ All button sizes are supported, but avoid mixing sizes within the same button gr ``` +```jsx react +import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + Left + Center + Right + + +

+ + + Left + Center + Right + + +

+ + + Left + Center + Right + + +); +``` + ### Theme Buttons Theme buttons are supported through the button's `type` attribute. @@ -86,6 +128,52 @@ Theme buttons are supported through the button's `type` attribute. ``` +```jsx react +import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + Left + Center + Right + + +

+ + + Left + Center + Right + + +

+ + + Left + Center + Right + + +

+ + + Left + Center + Right + + +

+ + + Left + Center + Right + + +); +``` + ### Pill Buttons Pill buttons are supported through the button's `pill` attribute. @@ -114,6 +202,36 @@ Pill buttons are supported through the button's `pill` attribute. ``` +```jsx react +import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + Left + Center + Right + + +

+ + + Left + Center + Right + + +

+ + + Left + Center + Right + + +); +``` + ### Dropdowns in Button Groups Dropdowns can be placed inside button groups as long as the trigger is an `` element. @@ -133,6 +251,31 @@ Dropdowns can be placed inside button groups as long as the trigger is an ` ``` +```jsx react +import { + SlButton, + SlButtonGroup, + SlDropdown, + SlMenu, + SlMenuItem, +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Button + Button + + Dropdown + + Item 1 + Item 2 + Item 3 + + + +); +``` + ### Split Buttons Create a split button using a button and a dropdown. @@ -151,6 +294,30 @@ Create a split button using a button and a dropdown. ``` +```jsx react +import { + SlButton, + SlButtonGroup, + SlDropdown, + SlMenu, + SlMenuItem, +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Save + + + + Save + Save as… + Save all + + + +); +``` + ### Tooltips in Button Groups Buttons can be wrapped in tooltips to provide more detail when the user interacts with them. @@ -171,6 +338,32 @@ Buttons can be wrapped in tooltips to provide more detail when the user interact ``` +```jsx react +import { + SlButton, + SlButtonGroup, + SlTooltip +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + Left + + + + Center + + + + Right + + + +); +``` + ### Toolbar Example Create interactive toolbars with button groups. @@ -218,4 +411,60 @@ Create interactive toolbars with button groups. ``` +```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 = () => ( + <> +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +); +``` + [component-metadata:sl-button-group] diff --git a/docs/components/button.md b/docs/components/button.md index 075f13ef7..f8234ef5d 100644 --- a/docs/components/button.md +++ b/docs/components/button.md @@ -8,6 +8,14 @@ Buttons represent actions that are available to the user. Button ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + Button +); +``` + ## Examples ### Types @@ -23,6 +31,21 @@ Use the `type` attribute to set the button's type. Danger ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Default + Primary + Success + Neutral + Warning + Danger + +); +``` + ### Sizes Use the `size` attribute to change a button's size. @@ -33,6 +56,18 @@ Use the `size` attribute to change a button's size. Large ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Small + Medium + Large + +); +``` + ### Outline Buttons Use the `outline` attribute to draw outlined buttons with transparent backgrounds. @@ -46,6 +81,21 @@ Use the `outline` attribute to draw outlined buttons with transparent background Danger ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Default + Primary + Success + Neutral + Warning + Danger + +); +``` + ### Pill Buttons Use the `pill` attribute to give buttons rounded edges. @@ -56,6 +106,18 @@ Use the `pill` attribute to give buttons rounded edges. Large ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Small + Medium + Large + +); +``` + ### Circle Buttons Use the `circle` attribute to create circular icon buttons. @@ -66,6 +128,18 @@ Use the `circle` attribute to create circular icon buttons. ``` +```jsx react +import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + + +); +``` + ### Text Buttons Use the `text` type to create text buttons that share the same size as regular buttons but don't have backgrounds or borders. @@ -76,6 +150,18 @@ Use the `text` type to create text buttons that share the same size as regular b Text ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Text + Text + Text + +); +``` + ### 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 `` 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. @@ -87,6 +173,19 @@ It's often helpful to have a button that works like a link. This is possible by Disabled ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Link + New Window + Download + Disabled + +); +``` + ?> 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 @@ -99,6 +198,18 @@ As expected, buttons can be given a custom width by setting its `width`. This is Large ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Small + Medium + Large + +); +``` + ### Prefix and Suffix Icons Use the `prefix` and `suffix` slots to add icons. @@ -157,6 +268,66 @@ Use the `prefix` and `suffix` slots to add icons. ``` +```jsx react +import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + Settings + + + + + Refresh + + + + + + Open + + +

+ + + + Settings + + + + + Refresh + + + + + + Open + + +

+ + + + Settings + + + + + Refresh + + + + + + Open + + +); +``` + ### Caret Use the `caret` attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or popover. @@ -167,6 +338,18 @@ Use the `caret` attribute to add a dropdown indicator when a button will trigger Large ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Small + Medium + Large + +); +``` + ### 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. @@ -180,6 +363,21 @@ Use the `loading` attribute to make a button busy. The width will remain the sam Danger ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Default + Primary + Success + Neutral + Warning + Danger + +); +``` + ### Disabled Use the `disabled` attribute to disable a button. Clicks will be suppressed until the disabled state is removed. @@ -193,6 +391,21 @@ Use the `disabled` attribute to disable a button. Clicks will be suppressed unti Danger ``` +```jsx react +import { SlButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Default + Primary + Success + Neutral + Warning + Danger + +); +``` + ### 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 type attribute instead of a class (e.g. `sl-button[type="primary"]`). diff --git a/docs/components/card.md b/docs/components/card.md index 0c54fc75f..c4989deb2 100644 --- a/docs/components/card.md +++ b/docs/components/card.md @@ -39,6 +39,53 @@ Cards can be used to group related subjects in a container. ``` +```jsx react +import { + SlButton, + SlCard, + SlRating +} from '@shoelace-style/shoelace/dist/react'; + +const css = ` + .card-overview { + max-width: 300px; + } + + .card-overview small { + color: rgb(var(--sl-color-neutral-500)); + } + + .card-overview [slot="footer"] { + display: flex; + justify-content: space-between; + align-items: center; + } +`; + +const App = () => ( + <> + + A kitten sits patiently between a terracotta pot and decorative grasses. + + Mittens
+ This kitten is as cute as he is playful. Bring him home today!
+ 6 weeks old + +
+ More Info + +
+ + + + +); +``` + ## Examples ## Basic Card @@ -57,6 +104,26 @@ Basic cards aren't very exciting, but they can display any content you want them ``` +```jsx react +import { SlCard } from '@shoelace-style/shoelace/dist/react'; + +const css = ` + .card-basic { + max-width: 300px; + } +`; + +const App = () => ( + <> + + This is just a basic card. No image, no header, and no footer. Just your content. + + + + +); +``` + ## Card with Header Headers can be used to display titles and more. @@ -73,26 +140,66 @@ Headers can be used to display titles and more. ``` +```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 = () => ( + <> + +
+ Header Title + + +
+ + This card has a header. You can put all sorts of things in it! + + + + +); +``` + ## Card with Footer Footers can be used to display actions, summaries, or other relevant content. @@ -120,6 +227,41 @@ Footers can be used to display actions, summaries, or other relevant content. ``` +```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 = () => ( + <> + + This card has a footer. You can put all sorts of things in it! + +
+ + Preview +
+ + + + +); +``` + ## Images Cards accept an `image` slot. The image is displayed atop the card and stretches to fit. @@ -141,4 +283,29 @@ Cards accept an `image` slot. The image is displayed atop the card and stretches ``` +```jsx react +import { SlCard } from '@shoelace-style/shoelace/dist/react'; + +const css = ` + .card-image { + max-width: 300px; + } +`; + +const App = () => ( + <> + + A kitten walks towards camera on top of pallet. + This is a kitten, but not just any kitten. This kitten likes walking along pallets. + + + + +); +``` + [component-metadata:sl-card] diff --git a/docs/components/checkbox.md b/docs/components/checkbox.md index 10a6f8adf..a9045f7c0 100644 --- a/docs/components/checkbox.md +++ b/docs/components/checkbox.md @@ -8,6 +8,14 @@ Checkboxes allow the user to toggle an option on or off. Checkbox ``` +```jsx react +import { SlCheckbox } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + Checkbox +); +``` + ?> This component doesn't work with standard forms. Use [``](/components/form) instead. ## Examples @@ -20,6 +28,14 @@ Use the `checked` attribute to activate the checkbox. Checked ``` +```jsx react +import { SlCheckbox } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + Checked +); +``` + ### Indeterminate Use the `indeterminate` attribute to make the checkbox indeterminate. @@ -28,6 +44,14 @@ Use the `indeterminate` attribute to make the checkbox indeterminate. Indeterminate ``` +```jsx react +import { SlCheckbox } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + Indeterminate +); +``` + ### Disabled Use the `disabled` attribute to disable the checkbox. @@ -36,4 +60,12 @@ Use the `disabled` attribute to disable the checkbox. Disabled ``` +```jsx react +import { SlCheckbox } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + Disabled +); +``` + [component-metadata:sl-checkbox] diff --git a/docs/components/color-picker.md b/docs/components/color-picker.md index 87b736444..a39579a88 100644 --- a/docs/components/color-picker.md +++ b/docs/components/color-picker.md @@ -8,6 +8,14 @@ Color pickers allow the user to select a color. ``` +```jsx react +import { SlColorPicker } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ## Examples ### Opacity @@ -18,6 +26,14 @@ Use the `opacity` attribute to enable the opacity slider. When this is enabled, ``` +```jsx react +import { SlColorPicker } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### Formats Set the color picker's format with the `format` attribute. Valid options include `hex`, `rgb`, and `hsl`. Note that the color picker's input will accept any parsable format (including CSS color names) regardless of this option. @@ -30,6 +46,18 @@ To prevent users from toggling the format themselves, add the `no-format-toggle` ``` +```jsx react +import { SlColorPicker } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + + +); +``` + ### Sizes Use the `size` attribute to change the color picker's trigger size. @@ -40,6 +68,17 @@ Use the `size` attribute to change the color picker's trigger size. ``` +```jsx react +import { SlColorPicker } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + + +); +``` ### Inline @@ -49,4 +88,12 @@ The color picker can be rendered inline instead of in a dropdown using the `inli ``` +```jsx react +import { SlColorPicker } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + [component-metadata:sl-color-picker] diff --git a/docs/components/details.md b/docs/components/details.md index d2cef8325..d23541f80 100644 --- a/docs/components/details.md +++ b/docs/components/details.md @@ -11,6 +11,17 @@ Details show a brief summary and expand to show additional content. ``` +```jsx react +import { SlDetails } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + 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. + +); +``` + ## Examples ### Disabled @@ -24,6 +35,17 @@ Use the `disable` attribute to prevent the details from expanding. ``` +```jsx react +import { SlDetails } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + 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. + +); +``` + ### 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. diff --git a/docs/components/dialog.md b/docs/components/dialog.md index 3e8fc79a1..e7348a11a 100644 --- a/docs/components/dialog.md +++ b/docs/components/dialog.md @@ -22,6 +22,28 @@ Dialogs, sometimes called "modals", appear above the page and require the user's ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)}> + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + setOpen(false)}> + Close + + + + setOpen(true)}>Open Dialog + + ); +}; +``` + ## UX Tips - Use a dialog when you immediately require the user's attention, e.g. confirming a destructive action. @@ -52,6 +74,33 @@ Use the `--width` custom property to set the dialog's width. ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)} + > + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + setOpen(false)}> + Close + + + + setOpen(true)}>Open Dialog + + ); +}; +``` + ### 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. @@ -76,6 +125,35 @@ By design, a dialog's height will never exceed that of the viewport. As such, di ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)}> +
+

Scroll down and give it a try! 👇

+
+ + setOpen(false)}> + Close + + + + setOpen(true)}>Open Dialog + + ); +}; +``` + ### 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. @@ -102,6 +180,33 @@ To keep the dialog open in such cases, you can cancel the `sl-request-close` eve ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + event.preventDefault()} + onSlAfterHide={() => setOpen(false)} + > + This dialog will not close unless you use the button below. + setOpen(false)}> + Save & Close + + + + setOpen(true)}>Open Dialog + + ); +}; +``` + ### Customizing Initial Focus By default, the dialog's panel will gain focus when opened. This allows the first tab press to focus on the first tabbable element within the dialog. To set focus on a different element, listen for and cancel the `sl-initial-focus` event. @@ -130,4 +235,41 @@ By default, the dialog's panel will gain focus when opened. This allows the firs ``` +```jsx react +import { useRef, useState } from 'react'; +import { + SlButton, + SlDialog, + SlInput +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const input = useRef(null); + const [open, setOpen] = useState(false); + + function handleInitialFocus(event) { + event.preventDefault(); + input.current.focus(); + } + + return ( + <> + setOpen(false)} + > + + setOpen(false)}> + Close + + + + setOpen(true)}>Open Dialog + + ); +}; +``` + [component-metadata:sl-dialog] diff --git a/docs/components/divider.md b/docs/components/divider.md index ba867e405..5af5b4389 100644 --- a/docs/components/divider.md +++ b/docs/components/divider.md @@ -8,6 +8,13 @@ Dividers are used to visually separate or group elements. ``` +```jsx react +import { SlDivider } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` ## Examples ### Width @@ -18,6 +25,14 @@ Use the `--width` custom property to change the width of the divider. ``` +```jsx react +import { SlDivider } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### Color Use the `--color` custom property to change the color of the divider. @@ -26,6 +41,14 @@ Use the `--color` custom property to change the color of the divider. ``` +```jsx react +import { SlDivider } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### Spacing Use the `--spacing` custom property to change the amount of space between the divider and it's neighboring elements. @@ -38,6 +61,18 @@ Use the `--spacing` custom property to change the amount of space between the di ``` +```jsx react +import { SlDivider } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + Above + + Below + +); +``` + ### 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. @@ -52,6 +87,26 @@ Add the `vertical` attribute to draw the divider in a vertical orientation. The ``` +```jsx react +import { SlDivider } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( +
+ First + + Middle + + Last +
+); +``` + ### Menu Dividers Use dividers in [menus](/components/menu) to visually group menu items. @@ -68,4 +123,30 @@ Use dividers in [menus](/components/menu) to visually group menu items. ``` +```jsx react +import { + SlDivider, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Option 1 + Option 2 + Option 3 + + Option 4 + Option 5 + Option 6 + +); +``` + [component-metadata:sl-divider] diff --git a/docs/components/drawer.md b/docs/components/drawer.md index b82139d04..a869d7acf 100644 --- a/docs/components/drawer.md +++ b/docs/components/drawer.md @@ -22,6 +22,28 @@ Drawers slide in from a container to expose additional options and information. ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)}> + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + setOpen(false)}> + Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + ## Examples ### Slide in From Start @@ -46,6 +68,33 @@ By default, drawers slide in from the end. To make the drawer slide in from the ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)} + > + This drawer slides in from the start. + setOpen(false)}> + Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + ### Slide in From Top To make the drawer slide in from the top, set the `placement` attribute to `top`. @@ -68,6 +117,33 @@ To make the drawer slide in from the top, set the `placement` attribute to `top` ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)} + > + This drawer slides in from the top. + setOpen(false)}> + Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + ### Slide in From Bottom To make the drawer slide in from the bottom, set the `placement` attribute to `bottom`. @@ -90,6 +166,33 @@ To make the drawer slide in from the bottom, set the `placement` attribute to `b ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)} + > + This drawer slides in from the bottom. + setOpen(false)}> + Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + ### Contained to an Element By default, the drawer slides out of its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make the drawer slide out of its parent element, add the `contained` attribute and `position: relative` to the parent. @@ -118,6 +221,47 @@ By default, the drawer slides out of its [containing block](https://developer.mo ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> +
+ The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer opens. + + setOpen(false)} + style={{ '--size': '50%' }} + > + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + setOpen(false)}> + Close + + +
+ + setOpen(true)}>Open Drawer + + ); +}; +``` + ### 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`. @@ -140,6 +284,32 @@ Use the `--size` custom property to set the drawer's size. This will be applied ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)} + style={{ '--size': '50vw' }} + > + This drawer is always 50% of the viewport. + setOpen(false)}> + Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + ### 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. @@ -164,6 +334,34 @@ By design, a drawer's height will never exceed 100% of its container. As such, d ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + setOpen(false)}> +
+

Scroll down and give it a try! 👇

+
+ setOpen(false)}> + Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + ### 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. @@ -173,7 +371,7 @@ To keep the drawer open in such cases, you can cancel the `sl-request-close` eve ```html preview - This dialog will not close unless you use the button below. + This drawer will not close unless you use the button below. Save & Close @@ -191,6 +389,33 @@ To keep the drawer open in such cases, you can cancel the `sl-request-close` eve ``` +```jsx react +import { useState } from 'react'; +import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [open, setOpen] = useState(false); + + return ( + <> + event.preventDefault()} + onSlAfterHide={() => setOpen(false)} + > + This drawer will not close unless you use the button below. + setOpen(false)}> + Save & Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + ### Customizing Initial Focus By default, the drawer's panel will gain focus when opened. This allows the first tab press to focus on the first tabbable element within the drawer. To set focus on a different element, listen for and cancel the `sl-initial-focus` event. @@ -219,4 +444,41 @@ By default, the drawer's panel will gain focus when opened. This allows the firs ``` +```jsx react +import { useRef, useState } from 'react'; +import { + SlButton, + SlDrawer, + SlInput +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const input = useRef(null); + const [open, setOpen] = useState(false); + + function handleInitialFocus(event) { + event.preventDefault(); + input.current.focus(); + } + + return ( + <> + setOpen(false)} + > + + setOpen(false)}> + Close + + + + setOpen(true)}>Open Drawer + + ); +}; +``` + [component-metadata:sl-drawer] diff --git a/docs/components/dropdown.md b/docs/components/dropdown.md index f84a11980..97dc6215d 100644 --- a/docs/components/dropdown.md +++ b/docs/components/dropdown.md @@ -31,6 +31,40 @@ Dropdowns are designed to work well with [menus](/components/menu) to provide a ``` +```jsx react +import { + SlButton, + SlDivider, + SlDropdown, + SlIcon, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Dropdown + + Dropdown Item 1 + Dropdown Item 2 + Dropdown Item 3 + + Checked + Disabled + + + Prefix + + + + Suffix Icon + + + + +); +``` + ## Examples ### Getting the Selected Item @@ -60,6 +94,33 @@ When dropdowns are used with [menus](/components/menu), you can listen for the ` ``` +```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 ( + + Edit + + Cut + Copy + Paste + + + ); +}; +``` + 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 @@ -86,6 +147,40 @@ Alternatively, you can listen for the `click` event on individual menu items. No ``` +```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 ( + + Edit + + Cut + Copy + Paste + + + ); +}; +``` + ### 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. @@ -104,6 +199,30 @@ The preferred placement of the dropdown can be set with the `placement` attribut ``` +```jsx react +import { + SlButton, + SlDivider, + SlDropdown, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Edit + + Cut + Copy + Paste + + Find + Replace + + +); +``` + ### Distance The distance from the panel to the trigger can be customized using the `distance` attribute. This value is specified in pixels. @@ -122,6 +241,30 @@ The distance from the panel to the trigger can be customized using the `distance ``` +```jsx react +import { + SlButton, + SlDivider, + SlDropdown, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Edit + + Cut + Copy + Paste + + Find + Replace + + +); +``` + ### Skidding The offset of the panel along the trigger can be customized using the `skidding` attribute. This value is specified in pixels. @@ -140,6 +283,30 @@ The offset of the panel along the trigger can be customized using the `skidding` ``` +```jsx react +import { + SlButton, + SlDivider, + SlDropdown, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Edit + + Cut + Copy + Paste + + Find + Replace + + +); +``` + ### 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. @@ -174,4 +341,49 @@ Dropdown panels will be clipped if they're inside a container that has `overflow ``` +```jsx react +import { + SlButton, + SlDivider, + SlDropdown, + SlIcon, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const css = ` + .dropdown-hoist { + border: solid 2px rgb(var(--sl-panel-border-color)); + padding: var(--sl-spacing-medium); + overflow: hidden; + } +`; + +const App = () => ( + <> +
+ + No Hoist + + Item 1 + Item 2 + Item 3 + + + + + Hoist + + Item 1 + Item 2 + Item 3 + + +
+ + + +); +``` + [component-metadata:sl-dropdown] diff --git a/docs/components/format-bytes.md b/docs/components/format-bytes.md index 682083e29..1f7be9837 100644 --- a/docs/components/format-bytes.md +++ b/docs/components/format-bytes.md @@ -20,6 +20,34 @@ Formats a number as a human readable bytes value. ``` + +```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 in size. +

+ setValue(event.target.value)} + /> + + ); +}; +``` + ## Examples ### Formatting Bytes @@ -33,6 +61,20 @@ Set the `value` attribute to a number to get the value in bytes. ``` + +```jsx react +import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> +
+
+
+ + +); +``` + ### Formatting Bits To get the value in bits, set the `unit` attribute to `bits`. @@ -44,6 +86,19 @@ To get the value in bits, set the `unit` attribute to `bits`. ``` +```jsx react +import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> +
+
+
+ + +); +``` + ### Localization Use the `locale` attribute to set the number formatting locale. @@ -55,4 +110,17 @@ Use the `locale` attribute to set the number formatting locale. ``` +```jsx react +import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> +
+
+
+ + +); +``` + [component-metadata:sl-format-bytes] diff --git a/docs/components/format-date.md b/docs/components/format-date.md index ba481cb69..7d7ff8c77 100644 --- a/docs/components/format-date.md +++ b/docs/components/format-date.md @@ -11,11 +11,18 @@ Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://dev ``` +```jsx react +import { SlFormatDate } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + 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. ?> 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 @@ -42,6 +49,32 @@ Formatting options are based on those found in the [`Intl.DateTimeFormat` API](h ``` +```jsx react +import { SlFormatDate } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + {/* Human-readable date */} +
+ + {/* Time */} +
+ + {/* Weekday */} +
+ + {/* Month */} +
+ + {/* Year */} +
+ + {/* No formatting options */} + + +); +``` + ### 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`. @@ -51,6 +84,17 @@ By default, the browser will determine whether to use 12-hour or 24-hour time. T ``` +```jsx react +import { SlFormatDate } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> +
+ + +); +``` + ### Localization Use the `locale` attribute to set the date/time formatting locale. @@ -58,7 +102,19 @@ Use the `locale` attribute to set the date/time formatting locale. ```html preview English:
French:
-Russian:
+Russian: +``` + +```jsx react +import { SlFormatDate } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + English:
+ French:
+ Russian: + +); ``` [component-metadata:sl-format-date] diff --git a/docs/components/format-number.md b/docs/components/format-number.md index f96c3cab5..ae5d6c093 100644 --- a/docs/components/format-number.md +++ b/docs/components/format-number.md @@ -22,6 +22,29 @@ Localization is handled by the browser's [`Intl.NumberFormat` API](https://devel ``` +```jsx react +import { useState } from 'react'; +import { SlFormatNumber, SlInput } from '@shoelace-style/shoelace/dist/react'; + +const App = () => { + const [value, setValue] = useState(1000); + + return ( +
+ +

+ setValue(event.target.value)} + /> +
+ ); +}; +``` + ## Examples ### Percentages @@ -30,12 +53,26 @@ To get the value as a percent, set the `type` attribute to `percent`. ```html preview
-
-
-
+
+
+
``` +```jsx react +import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> +
+
+
+
+ + +); +``` + ### Localization Use the `locale` attribute to set the number formatting locale. @@ -46,6 +83,18 @@ German: < Russian: ``` +```jsx react +import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + English:
+ German:
+ Russian: + +); +``` + ### 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 `locale` to ensure the the number is formatted correctly for the target locale. @@ -58,4 +107,18 @@ To format a number as a monetary value, set the `type` attribute to `currency` a ``` +```jsx react +import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> +
+
+
+
+ + +); +``` + [component-metadata:sl-format-number] diff --git a/docs/components/icon-button.md b/docs/components/icon-button.md index a2d5a8386..26472158a 100644 --- a/docs/components/icon-button.md +++ b/docs/components/icon-button.md @@ -10,6 +10,14 @@ For a full list of icons that come bundled with Shoelace, refer to the [icon com ``` +```jsx react +import { SlIconButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ## Examples ### Sizes @@ -22,6 +30,18 @@ Icon buttons inherit their parent element's `font-size`. ``` +```jsx react +import { SlIconButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + <> + + + + +); +``` + ### 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. @@ -49,6 +69,33 @@ Icon buttons are designed to have a uniform appearance, so their color is not in ``` +```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 = () => ( +
+ + + +
+); +``` + ### Link Buttons Use the `href` attribute to convert the button to a link. @@ -57,6 +104,19 @@ Use the `href` attribute to convert the button to a link. ``` +```jsx react +import { SlIconButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + ### Icon Button with Tooltip Wrap a tooltip around an icon button to provide contextual information to the user. @@ -67,6 +127,16 @@ Wrap a tooltip around an icon button to provide contextual information to the us ``` +```jsx react +import { SlIconButton, SlTooltip } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + + +); +``` + ### Disabled Use the `disabled` attribute to disable the icon button. @@ -75,4 +145,12 @@ Use the `disabled` attribute to disable the icon button. ``` +```jsx react +import { SlIconButton } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); +``` + [component-metadata:sl-icon-button] diff --git a/docs/components/icon.md b/docs/components/icon.md index 0b6777506..eec9ec10b 100644 --- a/docs/components/icon.md +++ b/docs/components/icon.md @@ -54,12 +54,46 @@ Icons are sized relative to the current font size. To change their size, set the ``` +```jsx react +import { SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( +
+ + + + + + + + + + + + + + + + +
+); +``` + ### 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 - + +``` + + +```jsx react +import { SlIcon } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); ``` ## Icon Libraries diff --git a/docs/components/image-comparer.md b/docs/components/image-comparer.md index 5a304450b..6fcabab79 100644 --- a/docs/components/image-comparer.md +++ b/docs/components/image-comparer.md @@ -13,6 +13,17 @@ For best results, use images that share the same dimensions. The slider can be c ``` +```jsx react +import { SlImageComparer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Grayscale version of kittens in a basket looking around. + Color version of kittens in a basket looking around. + +); +``` + ## Examples ### Initial Position @@ -26,4 +37,15 @@ Use the `position` attribute to set the initial position of the slider. This is ``` +```jsx react +import { SlImageComparer } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + A person sitting on bricks wearing untied boots. + A person sitting on a yellow curb tying shoelaces on a boot. + +); +``` + [component-metadata:sl-image-comparer] diff --git a/docs/components/include.md b/docs/components/include.md index b2e061701..17d6cbe85 100644 --- a/docs/components/include.md +++ b/docs/components/include.md @@ -8,8 +8,16 @@ Included files are asynchronously requested using `window.fetch()`. Requests are The included content will be inserted into the `` element's default slot so it can be easily accessed and styled through the light DOM. -```html preview no-codepen - +```html preview + +``` + +```jsx react +import { SlInclude } from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + +); ``` ## Examples @@ -21,7 +29,7 @@ When an include file loads successfully, the `sl-load` event will be emitted. Yo 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 - + ``` +```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 ( + + Option 1 + Option 2 + Option 3 + + ); +}; +``` + [component-metadata:sl-menu-item] diff --git a/docs/components/menu-label.md b/docs/components/menu-label.md index 600e3043d..b89690e8e 100644 --- a/docs/components/menu-label.md +++ b/docs/components/menu-label.md @@ -20,4 +20,33 @@ Menu labels are used to describe a group of menu items. ``` +```jsx react +import { + SlDivider, + SlMenu, + SlMenuLabel, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Fruits + Apple + Banana + Orange + + Vegetables + Broccoli + Carrot + Zucchini + +); +``` + [component-metadata:sl-menu-label] diff --git a/docs/components/menu.md b/docs/components/menu.md index a0ea31ead..5832698e2 100644 --- a/docs/components/menu.md +++ b/docs/components/menu.md @@ -18,6 +18,32 @@ You can use [menu items](/components/menu-item), [menu labels](/components/menu- ``` +```jsx react +import { + SlDivider, + SlMenu, + SlMenuItem +} from '@shoelace-style/shoelace/dist/react'; + +const App = () => ( + + Undo + Redo + + Cut + Copy + Paste + Delete + +); +``` + ?> 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 `