# PlayCanvas Web Components [![NPM Version](https://img.shields.io/npm/v/@playcanvas/web-components)](https://www.npmjs.com/package/@playcanvas/web-components) [![NPM Downloads](https://img.shields.io/npm/dw/@playcanvas/web-components)](https://npmtrends.com/@playcanvas/web-components) [![License](https://img.shields.io/npm/l/@playcanvas/web-components)](https://github.com/playcanvas/web-components/blob/main/LICENSE) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=flat&logo=discord&logoColor=white&color=black)](https://discord.gg/RSaMRzg) [![Reddit](https://img.shields.io/badge/Reddit-FF4500?style=flat&logo=reddit&logoColor=white&color=black)](https://www.reddit.com/r/PlayCanvas) [![X](https://img.shields.io/badge/X-000000?style=flat&logo=x&logoColor=white&color=black)](https://x.com/intent/follow?screen_name=playcanvas) | [User Manual](https://developer.playcanvas.com/user-manual/web-components) | [API Reference](https://api.playcanvas.com/web-components) | [Examples](https://playcanvas.github.io/web-components/examples) | [Blog](https://blog.playcanvas.com) | [Forum](https://forum.playcanvas.com) | PlayCanvas Web Components are a set of custom HTML elements for building 3D interactive web apps. Using the declarative nature of HTML makes it both easy and fun to incorporate 3D into your website. Check out this simple example: ```html ``` ## Examples PlayCanvas Web Components examples gallery showing interactive 3D demos Explore the [PlayCanvas Web Components examples gallery](https://playcanvas.github.io/web-components/examples). ## Getting Started The PlayCanvas Engine is a peer dependency, so your page needs an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) that tells the browser where to find both packages. **CDN (no install, no build step)** — load both from jsDelivr: ```html ``` **npm** — for projects with a `package.json`, dev server or bundler: ```bash npm install playcanvas @playcanvas/web-components ``` Then point the import map at the installed packages: ```html ``` **New project** — scaffold a Vite and TypeScript app from a runnable starter: ```bash npm create playcanvas@latest my-app -- -f web-components ``` The [Getting Started Guide](https://developer.playcanvas.com/user-manual/web-components/getting-started/) walks through a complete first page, version pinning and bundler setups. ## Editor Support The package ships a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest), which editors use to offer tag and attribute completions, valid attribute values and hover documentation when authoring HTML. **VS Code** — add the following to your workspace `.vscode/settings.json`: ```json { "html.customData": [ "./node_modules/@playcanvas/web-components/dist/vscode.html-custom-data.json" ] } ``` **JetBrains IDEs** (WebStorm, IntelliJ IDEA) — no setup required. The IDE discovers the bundled `web-types.json` automatically. **Other tooling** — the manifest itself is at `@playcanvas/web-components/dist/custom-elements.json` and is declared in the package's `customElements` field, which is how tools such as `lit-analyzer` and Storybook locate it. ## Developing with AI Coding agents: start from the [Web Components guides index](https://developer.playcanvas.com/user-manual/web-components/llms.txt) and the [Web Components API index](https://api.playcanvas.com/web-components/llms.txt), which link a Markdown version of every page. ## Development ### Setting Up Local Development 1. Clone the repository: ```bash git clone https://github.com/playcanvas/web-components.git cd web-components ``` 2. Install dependencies: ```bash npm install ``` 3. Build the library in watch mode and start the development server: ```bash npm run dev ``` 4. Open http://localhost:3000/examples/ in your browser to see the examples. ### Building To build the library: ```bash npm run build ``` The built files will be available in the `dist` directory. ### API Documentation To generate API documentation: ```bash npm run docs ``` The documentation will be generated in the `docs` directory.