Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add themed css to getting started snippet #512

Merged
merged 2 commits into from
Aug 27, 2021
Merged

docs: add themed css to getting started snippet #512

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6ece6be
docs: add themed css to getting started snippet
bennypowers Aug 26, 2021
c9ee014
docs: add instructions to force light or dark themes
bennypowers Aug 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
37 changes: 33 additions & 4 deletions docs/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,51 @@ You can use Shoelace via CDN or by installing it locally.

The easiest way to install Shoelace is with the CDN. Just add the following tags to your page.

```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');">
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace.js"></script>
```

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.

### Forcing Light or Dark Themes

To force Shoelace to use the light theme, load the light stylesheet only. Since light theme is the default, you don't need to take any further steps.

```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>
```

To force the dark theme, set the `sl-theme-dark` class on the `<html>` element and load the dark stylesheet.

```html
<html class="sl-theme-dark">
<head>
<!-- ... -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace.js"></script>
</head>
<body>
<!-- ... -->
</body>
</html>
```

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.
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 `/scripts/shoelace` that serves static files from `node_modules/@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 `/scripts/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.

Expand Down Expand Up @@ -66,7 +95,7 @@ Here's an example that loads only the button component. Again, if you're not usi

<script type="module" data-shoelace="/scripts/shoelace">
import '@shoelace-style/shoelace/dist/components/button/button.js';

// <sl-button> is ready to use!
</script>
```
Expand Down Expand Up @@ -108,4 +137,4 @@ setBasePath('/dist/shoelace');
// <sl-button>, <sl-icon>, <sl-input>, and <sl-rating> are ready to use!
```

!> 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.
!> 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.