diff --git a/package-lock.json b/package-lock.json
index fecfd124f..cce044818 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2983,6 +2983,12 @@
"@types/node": "*"
}
},
+ "node_modules/@wc-toolkit/jsx-types": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/@wc-toolkit/jsx-types/-/jsx-types-1.3.0.tgz",
+ "integrity": "sha512-2rcRyPNEAdesFlokSSFBuCjpPPrMySk4NqyVJsqCs/WczcAUnIGwjnJk2fd/SNmzSjxGFRIFLAhXOgFOHLPvxQ==",
+ "dev": true
+ },
"node_modules/@web/browser-logs": {
"version": "0.4.0",
"resolved": "https://registry.npmjs.org/@web/browser-logs/-/browser-logs-0.4.0.tgz",
@@ -13985,6 +13991,9 @@
"qr-creator": "^1.0.0",
"style-observer": "^0.0.7"
},
+ "devDependencies": {
+ "@wc-toolkit/jsx-types": "^1.3.0"
+ },
"engines": {
"node": ">=14.17.0"
}
diff --git a/packages/webawesome/custom-elements-manifest.js b/packages/webawesome/custom-elements-manifest.js
index 5597c0c2b..6588d92f6 100644
--- a/packages/webawesome/custom-elements-manifest.js
+++ b/packages/webawesome/custom-elements-manifest.js
@@ -1,3 +1,4 @@
+import { jsxTypesPlugin } from '@wc-toolkit/jsx-types';
import { customElementJetBrainsPlugin } from 'custom-element-jet-brains-integration';
import { customElementVsCodePlugin } from 'custom-element-vs-code-integration';
// import { customElementVuejsPlugin } from 'custom-element-vuejs-integration';
@@ -164,6 +165,7 @@ export default {
],
}),
+ // Generate custom JetBrains data
customElementJetBrainsPlugin({
outdir: './dist-cdn',
excludeCss: true,
@@ -176,6 +178,12 @@ export default {
},
}),
+ // Generate JSX types (see https://wc-toolkit.com/integrations/jsx/)
+ jsxTypesPlugin({
+ fileName: 'custom-elements-jsx.d.ts',
+ outdir,
+ }),
+
//
// TODO - figure out why this broke when events were updated
//
diff --git a/packages/webawesome/docs/docs/index.md b/packages/webawesome/docs/docs/index.md
index 106d4a03f..b1b62f36f 100644
--- a/packages/webawesome/docs/docs/index.md
+++ b/packages/webawesome/docs/docs/index.md
@@ -22,6 +22,7 @@ To get everything included in Web Awesome, add the following code to the `
```
This snippet adds:
+
- **Web Awesome styles**, a collection of stylesheets including essential default theme styles, optional [styles for native elements](/docs/utilities/native) and optional [utility classes](/docs/utilities)
- **The autoloader**, a lightweight script watches the DOM for unregistered Web Awesome elements and lazy loads them for you — even if they're added dynamically
@@ -47,6 +48,7 @@ Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You
---
{# This looks weird, but without it, markdownItAttrs flags the raw calls incorrectly. #}
+
{%- raw -%}
{% if currentUser.hasPro %}
@@ -57,7 +59,6 @@ Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You
{% endraw %}
-
## Advanced Setup
The autoloader is the easiest way to use Web Awesome, but different projects (or your own preferences!) may require different installation methods.
@@ -98,15 +99,15 @@ Web Awesome does not a provide a single import with all Web Awesome components.
```js
// Option 1: import all Web Awesome styles
-import "@awesome.me/webawesome/dist/styles/webawesome.css"
+import '@awesome.me/webawesome/dist/styles/webawesome.css';
// Option 2: import only the default theme
-import "@awesome.me/webawesome/dist/styles/themes/default.css"
+import '@awesome.me/webawesome/dist/styles/themes/default.css';
//
-import "@awesome.me/webawesome/dist/components/button/button.js"
+import '@awesome.me/webawesome/dist/components/button/button.js';
//
-import "@awesome.me/webawesome/dist/components/input/input.js"
+import '@awesome.me/webawesome/dist/components/input/input.js';
```
Once they've been imported, you can use them in your HTML normally. Component imports are located in the "Importing" section of each component's documentation.
@@ -148,13 +149,63 @@ Most of the magic behind assets is handled internally by Web Awesome, but if you
```
-## The difference between `/dist` and `/dist-cdn`
+### The Difference Between `/dist` & `/dist-cdn`
-If you have Web Awesome installed locally via NPM, you'll notice 2 directories. `/dist-cdn` and `/cdn`.
+If you have Web Awesome installed locally via npm, you'll notice the following directories in the project's root:
-The `/dist-cdn` files are bundled differently than the `/dist` files. The `/dist-cdn` files come pre-bundled, which means all dependencies are "inlined" so there are no "bare" references like `import "lit"`. The `/dist` files **DO NOT** come pre-bundled, allowing your bundler of choice to more efficiently de-duplicate dependencies, resulting in smaller bundles and optimal code sharing.
+```
+dist/
+dist-cdn/
+```
-TLDR:
+The `dist-cdn` files come with everything bundled together, so you can use them directly without a build tool. The dist files keep dependencies separate, which lets your bundler optimize and share code more efficiently.
-- `@awesome.me/webawesome/dist-cdn` is for CDNs or people not using a bundler.
-- `@awesome.me/webawesome/dist` is for bundlers or importmaps.
+Use `dist-cdn` if you're loading directly in the browser or from a CDN. Use `dist` if you're using a bundler like Webpack or Vite.
+
+## React Users
+
+React 19+ [supports custom elements](https://react.dev/blog/2024/04/25/react-19#support-for-custom-elements), so you can import them and use them as you'd expect. Just make sure you've included your Web Awesome theme into your app first.
+
+```jsx
+import '@awesome.me/webawesome/dist/components/button/button.js';
+
+function App() {
+ return Button;
+}
+
+export default App;
+```
+
+If you're using TypeScript, you can add type safety using the types file located at:
+
+```
+node_modules/@awesome.me/webawesome/dist/custom-elements-jsx.d.ts
+```
+
+This gives you inline documentation, autocomplete, and type-safe validation for every component. You can add the types to your project by updating your `tsconfig.json` file as shown below.
+
+```json
+{
+ "compilerOptions": {
+ "types": ["node-modules/@awesome.me/webawesome/dist/custom-elements-jsx.d.ts"]
+ }
+}
+```
+
+Another way is to create a declaration file and extend JSX's `IntrinsicElements`:
+
+```ts
+import type { CustomElements, CustomCssProperties } from '@awesome.me/webawesome/dist/custom-elements-jsx.d.ts';
+
+declare module 'react' {
+ namespace JSX {
+ interface IntrinsicElements extends CustomElements {}
+ }
+ interface CSSProperties extends CustomCssProperties {}
+}
+```
+
+:::details React 18 and below
+React 18 and below have [poor support](https://custom-elements-everywhere.com/#react) for custom elements. For legacy versions of React, we provide React wrappers for every component. You can find the import instructions by selecting the _React_ tab from the _Importing_ section of each
+component's documentation.
+:::
diff --git a/packages/webawesome/docs/docs/resources/changelog.md b/packages/webawesome/docs/docs/resources/changelog.md
index 071d71803..00b8c75b4 100644
--- a/packages/webawesome/docs/docs/resources/changelog.md
+++ b/packages/webawesome/docs/docs/resources/changelog.md
@@ -16,6 +16,7 @@ Components with the Experimental badge sh
- Added the `animating` custom state to `` [pr:1214]
- Added `--wa-tooltip-border-color`, `--wa-tooltip-border-style`, and `--wa-tooltip-border-width` tokens [issue:1224]
- Added the `without-arrow` attribute to `` and `` to hide arrows without artifacts
+- Added JSX types for use with React and others [pr:1256]
### Bug Fixes and Improvements {data-no-outline}
diff --git a/packages/webawesome/package.json b/packages/webawesome/package.json
index 7632a804c..966cf135c 100644
--- a/packages/webawesome/package.json
+++ b/packages/webawesome/package.json
@@ -86,5 +86,8 @@
"*.{ts,js}": [
"prettier --write"
]
+ },
+ "devDependencies": {
+ "@wc-toolkit/jsx-types": "^1.3.0"
}
}