mirror of
https://github.com/shoelace-style/webawesome.git
synced 2026-01-12 04:09:12 +00:00
update framework docs
This commit is contained in:
konnorrogers
@@ -15,7 +15,7 @@ Angular [plays nice](https://custom-elements-everywhere.com/#angular) with custo
|
||||
To add Web Awesome to your Angular app, install the package from npm.
|
||||
|
||||
```bash
|
||||
npm install @shoelace-style/shoelace
|
||||
npm install @awesome.me/webawesome
|
||||
```
|
||||
|
||||
### Update the Angular Configuration
|
||||
@@ -32,28 +32,14 @@ Its also important to load the components by using a `<script>` tag into the ind
|
||||
...
|
||||
"styles": [
|
||||
"src/styles.scss",
|
||||
"@shoelace-style/shoelace/dist/themes/light.css"
|
||||
],
|
||||
"scripts": [
|
||||
"@shoelace-style/shoelace/dist/shoelace.js"
|
||||
]
|
||||
"@awesome.me/webawesome/dist/styles/webawesome.css"
|
||||
]
|
||||
...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Setting up the base path
|
||||
|
||||
Next, set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets in the `main.ts`. In this example, we'll use the CDN as a base path.
|
||||
|
||||
```jsx
|
||||
import { setBasePath } from '@shoelace-style/shoelace/%NPMDIR%/utilities/base-path';
|
||||
|
||||
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/');
|
||||
```
|
||||
|
||||
:::tip
|
||||
If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/%NPMDIR%/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.
|
||||
@@ -77,17 +63,19 @@ export class AppModule {}
|
||||
## Reference Web Awesome components in your Angular component code
|
||||
|
||||
```js
|
||||
import { SlDrawer } from '@shoelace-style/shoelace';
|
||||
// need to have both or Angular will tree shake the component out.
|
||||
import type { WaDrawer } from '@awesome.me/webawesome/dist/components/drawer/drawer.js';
|
||||
import "@awesome.me/webawesome/dist/components/drawer/drawer.js";
|
||||
|
||||
@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>'
|
||||
template: '<div id="page"><button (click)="showDrawer()">Show drawer</button><wa-drawer #drawer label="Drawer" class="drawer-focus" style="--size: 50vw"><p>Drawer content</p></wa-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>;
|
||||
drawer?: ElementRef<WaDrawer>;
|
||||
|
||||
...
|
||||
|
||||
@@ -109,5 +97,5 @@ export class DrawerExampleComponent implements OnInit {
|
||||
Now you can start using Web Awesome components in your app!
|
||||
|
||||
:::tip
|
||||
Are you using Web Awesome with Angular? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md)
|
||||
Are you using Web Awesome with Angular? [Help us improve this page!](https://github.com/shoelace-style/webawesome/blob/next/docs/frameworks/angular.md)
|
||||
:::
|
||||
@@ -13,23 +13,21 @@ Web Awesome offers a React version of every component to provide an idiomatic ex
|
||||
To add Web Awesome to your React app, install the package from npm.
|
||||
|
||||
```bash
|
||||
npm install @shoelace-style/shoelace
|
||||
npm install @awesome.me/webawesome
|
||||
```
|
||||
|
||||
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.
|
||||
Next, import the Web Awesome stylesheet, import the components you need, and then start using Web Awesome!
|
||||
|
||||
```jsx
|
||||
// App.jsx
|
||||
import '@shoelace-style/shoelace/%NPMDIR%/themes/light.css';
|
||||
import { setBasePath } from '@shoelace-style/shoelace/%NPMDIR%/utilities/base-path.js';
|
||||
// App.jsx (React 19, using native custom elements)
|
||||
import '@awesome.me/webawesome/dist/styles/webawesome.css';
|
||||
import '@awesome.me/webawesome/dist/components/button/button.js';
|
||||
|
||||
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/');
|
||||
export default function App () {
|
||||
return <wa-button>I'm a button!</wa-button>
|
||||
}
|
||||
```
|
||||
|
||||
:::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/%NPMDIR%/assets` into your app's `public` directory. Then you can point the base path to that folder instead.
|
||||
:::
|
||||
|
||||
Now you can start using components!
|
||||
|
||||
### Preact
|
||||
@@ -40,12 +38,12 @@ Preact users facing type errors using components may benefit from setting "paths
|
||||
|
||||
### Importing Components
|
||||
|
||||
Every Web Awesome 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.
|
||||
Every Web Awesome component is available to import as a React component. Note that we're importing the `<WaButton>` _React component_ instead of the `<wa-button>` _custom element_ in the example below.
|
||||
|
||||
```jsx
|
||||
import SlButton from '@shoelace-style/shoelace/%NPMDIR%/react/button/index.js';
|
||||
import WaButton from '@awesome.me/webawesome/react/button/index.js';
|
||||
|
||||
const MyComponent = () => <SlButton variant="primary">Click me</SlButton>;
|
||||
const MyComponent = () => <WaButton variant="primary">Click me</WaButton>;
|
||||
|
||||
export default MyComponent;
|
||||
```
|
||||
@@ -55,32 +53,35 @@ export default MyComponent;
|
||||
Previously, it was recommended to import from a single entrypoint like so:
|
||||
|
||||
```jsx
|
||||
import { SlButton } from '@shoelace-style/shoelace/%NPMDIR%/react';
|
||||
import { WaButton } from '@awesome.me/webawesome/dist/react';
|
||||
```
|
||||
|
||||
However, tree-shaking extra Web Awesome components proved to be a challenge. As a result, we now recommend cherry-picking components you want to use, rather than importing from a single entrypoint.
|
||||
|
||||
```diff
|
||||
- import { SlButton } from '@shoelace-style/shoelace/%NPMDIR%/react';
|
||||
+ import SlButton from '@shoelace-style/shoelace/%NPMDIR%/react/button/index.js';
|
||||
- import { WaButton } from '@awesome.me/webawesome/dist/react';
|
||||
+ import WaButton from '@awesome.me/webawesome/dist/react/button/index.js';
|
||||
```
|
||||
|
||||
You can find a copy + paste import for each component in the "importing" section of its documentation.
|
||||
|
||||
### Event Handling
|
||||
|
||||
Many Web Awesome 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`.
|
||||
Many Web Awesome components emit [native events](https://developer.mozilla.org/en-US/docs/Web/API/Event). For example, the [input component](/components/input) emits the `input` event when it receives input. In React, you can listen for the event using `onInput`.
|
||||
|
||||
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/%NPMDIR%/react/input/index.js';
|
||||
import WaInput from '@awesome.me/webawesome/dist/react/input/index.js';
|
||||
|
||||
function MyComponent() {
|
||||
const [value, setValue] = useState('');
|
||||
|
||||
return <SlInput value={value} onSlInput={event => setValue(event.target.value)} />;
|
||||
return <>
|
||||
<WaInput value={value} onInput={event => setValue(event.target.value)} />;
|
||||
<WaInput defaultValue={"Foo"} /> {/* This is an "uncontrolled input" */}
|
||||
</>
|
||||
}
|
||||
|
||||
export default MyComponent;
|
||||
@@ -90,13 +91,13 @@ If you're using TypeScript, it's important to note that `event.target` will be a
|
||||
|
||||
```tsx
|
||||
import { useState } from 'react';
|
||||
import SlInput from '@shoelace-style/shoelace/%NPMDIR%/react/input/index.js';
|
||||
import type SlInputElement from '@shoelace-style/shoelace/%NPMDIR%/components/input/input.js';
|
||||
import WaInput from '@awesome.me/webawesome/dist/react/input/index.js';
|
||||
import type WaInputElement from '@awesome.me/webawesome/dist/components/input/input.js';
|
||||
|
||||
function MyComponent() {
|
||||
const [value, setValue] = useState('');
|
||||
|
||||
return <SlInput value={value} onSlInput={event => setValue((event.target as SlInputElement).value)} />;
|
||||
return <WaInput value={value} onInput={event => setValue((event.target as WaInputElement).value)} />;
|
||||
}
|
||||
|
||||
export default MyComponent;
|
||||
@@ -106,16 +107,16 @@ You can also import the event type for use in your callbacks, shown below.
|
||||
|
||||
```tsx
|
||||
import { useCallback, useState } from 'react';
|
||||
import SlInput, { type SlInputEvent } from '@shoelace-style/shoelace/%NPMDIR%/react/input/index.js';
|
||||
import type SlInputElement from '@shoelace-style/shoelace/%NPMDIR%/components/input/input.js';
|
||||
import WaInput, { type WaInputEvent } from '@awesome.me/webawesome/dist/react/input/index.js';
|
||||
import type WaInputElement from '@awesome.me/webawesome/dist/components/input/input.js';
|
||||
|
||||
function MyComponent() {
|
||||
const [value, setValue] = useState('');
|
||||
const onInput = useCallback((event: SlInputEvent) => {
|
||||
const onInput = useCallback((event: WaInputEvent) => {
|
||||
setValue(event.detail);
|
||||
}, []);
|
||||
|
||||
return <SlInput value={value} onSlInput={event => setValue((event.target as SlInputElement).value)} />;
|
||||
return <WaInput value={value} onInput={event => setValue((event.target as WaInputElement).value)} />;
|
||||
}
|
||||
|
||||
export default MyComponent;
|
||||
@@ -178,7 +179,7 @@ To fix this, add the following to your `package.json` which tells the transpiler
|
||||
```js
|
||||
{
|
||||
"jest": {
|
||||
"transformIgnorePatterns": ["node_modules/(?!(@shoelace))"]
|
||||
"transformIgnorePatterns": ["node_modules/(?!(@awesome.me|lit|@lit-labs))"]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -188,5 +189,5 @@ These instructions are for apps created via Create React App. If you're using Je
|
||||
For more details, refer to Jest's [`transformIgnorePatterns` customization](https://jestjs.io/docs/tutorial-react-native#transformignorepatterns-customization) documentation.
|
||||
|
||||
:::tip
|
||||
Are you using Web Awesome with React? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/react.md)
|
||||
Are you using Web Awesome with React? [Help us improve this page!](https://github.com/shoelace-style/webawesome/blob/next/docs/frameworks/react.md)
|
||||
:::
|
||||
@@ -13,23 +13,17 @@ Svelte [plays nice](https://custom-elements-everywhere.com/#svelte) with custom
|
||||
To add Web Awesome to your Svelte app, install the package from npm.
|
||||
|
||||
```bash
|
||||
npm install @shoelace-style/shoelace
|
||||
npm install @awesome.me/webawesome
|
||||
```
|
||||
|
||||
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.
|
||||
Next, import the Web Awesome stylesheet, import the components you need, and then start using Web Awesome!
|
||||
|
||||
```jsx
|
||||
// main.js or main.ts
|
||||
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%/%CDNDIR%/');
|
||||
import '@awesome.me/webawesome/dist/styles/webawesome.css';
|
||||
import '@awesome.me/webawesome/dist/components/button/button.js';
|
||||
```
|
||||
|
||||
:::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.
|
||||
:::
|
||||
|
||||
## Usage
|
||||
|
||||
### QR code generator example
|
||||
@@ -37,16 +31,16 @@ If you'd rather not use the CDN for assets, you can create a build task that cop
|
||||
```jsx
|
||||
<h1>Live editing</h1>
|
||||
|
||||
<sl-input label="Message" value={message} oninput={event => message = event.target.value}></sl-input>
|
||||
<wa-input label="Message" value={message} oninput={event => message = event.target.value}></wa-input>
|
||||
|
||||
<sl-alert open>
|
||||
<sl-icon slot="icon" name="info-circle"></sl-icon>
|
||||
<wa-alert open>
|
||||
<wa-icon slot="icon" name="info-circle"></wa-icon>
|
||||
{message}
|
||||
</sl-alert>
|
||||
</wa-alert>
|
||||
|
||||
<script>
|
||||
import '@shoelace-style/shoelace/dist/components/alert/alert.js'
|
||||
import '@shoelace-style/shoelace/dist/components/input/input.js';
|
||||
import '@awesome.me/webawesome/dist/components/alert/alert.js'
|
||||
import '@awesome.me/webawesome/dist/components/input/input.js';
|
||||
|
||||
let message = $state('')
|
||||
</script>
|
||||
@@ -58,24 +52,24 @@ One caveat is there's currently Svelte only supports `bind:value` directive in `
|
||||
|
||||
```jsx
|
||||
// ❌ These do not work
|
||||
<sl-input bind:value="name"></sl-input>
|
||||
<wa-input bind:value="name"></wa-input>
|
||||
|
||||
<sl-select bind:value="job">
|
||||
<sl-option value="designer">Designer</sl-option>
|
||||
<sl-option value="developer">Developer</sl-option>
|
||||
</sl-select>
|
||||
<wa-select bind:value="job">
|
||||
<wa-option value="designer">Designer</wa-option>
|
||||
<wa-option value="developer">Developer</wa-option>
|
||||
</wa-select>
|
||||
|
||||
// ✅ These are a bit longer, but work
|
||||
<sl-input value={name} oninput={event => name = event.target.value}></sl-input>
|
||||
<wa-input value={name} oninput={event => name = event.target.value}></wa-input>
|
||||
|
||||
<sl-select value={job} onsl-input={event => job = event.target.value}>
|
||||
<sl-option value="designer">Designer</sl-option>
|
||||
<sl-option value="developer">Developer</sl-option>
|
||||
</sl-select>
|
||||
<wa-select value={job} oninput={event => job = event.target.value}>
|
||||
<wa-option value="designer">Designer</wa-option>
|
||||
<wa-option value="developer">Developer</wa-option>
|
||||
</wa-select>
|
||||
```
|
||||
|
||||
:::tip
|
||||
Are you using Web Awesome with Svelte? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/svelte.md)
|
||||
Are you using Web Awesome with Svelte? [Help us improve this page!](https://github.com/shoelace-style/webawesome/blob/next/docs/frameworks/svelte.md)
|
||||
:::
|
||||
|
||||
### Slots
|
||||
@@ -85,12 +79,12 @@ Slots in Web Awesome/web components are functionally the same as basic slots in
|
||||
Here is an example:
|
||||
|
||||
```jsx
|
||||
<sl-drawer label="Drawer" placement="start" class="drawer-placement-start" bind:open={drawerIsOpen}>
|
||||
<wa-drawer label="Drawer" placement="start" class="drawer-placement-start" bind:open={drawerIsOpen}>
|
||||
This drawer slides in from the start.
|
||||
<div slot="footer">
|
||||
<sl-button variant="primary" onclick={() => (drawerIsOpen = false)}>
|
||||
<wa-button variant="primary" onclick={() => (drawerIsOpen = false)}>
|
||||
Close
|
||||
</sl-button>
|
||||
</wa-button>
|
||||
</div>
|
||||
</sl-drawer>
|
||||
</wa-drawer>
|
||||
```
|
||||
@@ -17,31 +17,26 @@ These instructions are for Vue 2. If you're using Vue 3 or above, please see the
|
||||
To add Web Awesome to your Vue app, install the package from npm.
|
||||
|
||||
```bash
|
||||
npm install @shoelace-style/shoelace
|
||||
npm install @awesome.me/webawesome
|
||||
```
|
||||
|
||||
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.
|
||||
Next, import the Web Awesome stylesheet, import the components you need, and then start using Web Awesome!
|
||||
|
||||
```jsx
|
||||
import '@shoelace-style/shoelace/%NPMDIR%/themes/light.css';
|
||||
import { setBasePath } from '@shoelace-style/shoelace/%NPMDIR%/utilities/base-path';
|
||||
|
||||
setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/');
|
||||
// main.js or main.ts
|
||||
import '@awesome.me/webawesome/dist/styles/webawesome.css';
|
||||
import '@awesome.me/webawesome/dist/components/button/button.js';
|
||||
```
|
||||
|
||||
:::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 Web Awesome components. This is pretty easy because they all start with `sl-`.
|
||||
You'll need to tell Vue to ignore Web Awesome components. This is pretty easy because they all start with `wa-`.
|
||||
|
||||
```js
|
||||
import Vue from 'vue';
|
||||
import App from './App.vue';
|
||||
|
||||
Vue.config.ignoredElements = [/sl-/];
|
||||
Vue.config.ignoredElements = [/wa-/];
|
||||
|
||||
const app = new Vue({
|
||||
render: h => h(App)
|
||||
@@ -59,7 +54,7 @@ Now you can start using Web Awesome components in your app!
|
||||
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" />
|
||||
<wa-color-picker :swatches.prop="mySwatches" />
|
||||
```
|
||||
|
||||
### Two-way Binding
|
||||
@@ -68,9 +63,9 @@ One caveat is there's currently [no support for v-model on custom elements](http
|
||||
|
||||
```html
|
||||
<!-- ❌ This doesn't work -->
|
||||
<sl-input v-model="name"></sl-input>
|
||||
<wa-input v-model="name"></wa-input>
|
||||
<!-- ✅ This works, but it's a bit longer -->
|
||||
<sl-input :value="name" @input="name = $event.target.value"></sl-input>
|
||||
<wa-input :value="name" @input="name = $event.target.value"></wa-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 Web Awesome components. To install it, use this command.
|
||||
@@ -87,7 +82,7 @@ import Web AwesomeModelDirective from '@shoelace-style/vue-sl-model';
|
||||
import App from './App.vue';
|
||||
|
||||
Vue.use(Web AwesomeModelDirective);
|
||||
Vue.config.ignoredElements = [/sl-/];
|
||||
Vue.config.ignoredElements = [/wa-/];
|
||||
|
||||
const app = new Vue({
|
||||
render: h => h(App)
|
||||
@@ -99,9 +94,9 @@ 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>
|
||||
<wa-input v-sl-model="name"></wa-input>
|
||||
```
|
||||
|
||||
:::tip
|
||||
gre you using Web Awesome with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue-2.md)
|
||||
Are you using Web Awesome with Vue 2? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue-2.md)
|
||||
:::
|
||||
@@ -20,11 +20,12 @@ To add Web Awesome to your Vue app, install the package from npm.
|
||||
npm install @awesome.me/webawesome
|
||||
```
|
||||
|
||||
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.
|
||||
Next, import the Web Awesome stylesheet, import the components you need, and then start using Web Awesome!
|
||||
|
||||
```js
|
||||
```jsx
|
||||
// main.js or main.ts
|
||||
import '@awesome.me/webawesome/dist/themes/default.css';
|
||||
import '@awesome.me/webawesome/dist/styles/webawesome.css';
|
||||
import '@awesome.me/webawesome/dist/components/button/button.js';
|
||||
```
|
||||
|
||||
## Configuration
|
||||
@@ -95,7 +96,7 @@ One caveat is there's currently [no support for v-model on custom elements](http
|
||||
<wa-input :value="name" @input="name = $event.target.value"></wa-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 Web Awesome components.
|
||||
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-wa-model) adds a custom directive that will work just like `v-model` but for Web Awesome components.
|
||||
|
||||
### Slots
|
||||
|
||||
|
||||
Reference in New Issue
Block a user