# Installation
Install the **theui-svelte** component library in your project or start a new project with the boilerplate template. Install it to build fast and deliver faster.
## Installation
**Requirements:** Svelte 5.57.1 or newer, Tailwind CSS v4 and Node.js 22.12 or newer.
Follow one of the two methods to install the component library:
- Github boilerplate.
- Manual installation.
The form styles come with the package, so there is no Tailwind plugin to add by hand. The typography plugin is not included: install `@tailwindcss/typography` yourself if your own pages use its `prose` classes.
## Use Github Boilerplate
To install the starter template clone [this Github repo](https://github.com/mbparvezme/theui-svelte-starter) from your terminal using the following commands, replacing `my-app` with your desired project name.
**Clone from Github**
```bash
# Clone the project
git clone https://github.com/mbparvezme/theui-svelte-starter.git my-app
# Navigate to the project directory
cd my-app
# Install node modules
npm install
# Run the application
npm run dev
```
## Manual Installation
Easily add theui-svelte to your project via a GitHub boilerplate or manual installation. For manual setup:
- Install Sveltekit with TailwindCSS and theui-svelte
- Configure Tailwind CSS by updating the `./src/app.css` file.
2.1 Install
**Install SvelteKit**
```bash
# Create a SvelteKit project
# When prompted "What would you like to add to your project?", select tailwindcss
npx sv create my-app
cd my-app
# Add Tailwind CSS - if you didn't select tailwindcss during the project creation, run:
# npx sv add tailwindcss
# Install theui-svelte
npm install theui-svelte
```
2.2 Configuration
To integrate `theui-svelte` with your project, add the following lines to your `./src/app.css` file:
**./src/app.css**
```diff
@import 'tailwindcss';
+ @import 'theui-svelte/style';
```
That's it! You're ready to start building your awesome project. Now, run your application with:
**Run the development server**
```bash
# Run SvelteKit project
npm run dev
```
## Turn On AI Support
If you build with a coding assistant, one command hands it the rules it cannot guess. Run it in your project root once the library is installed:
**Point your coding agent at the library**
```bash
npx theui ai
```
It looks for the instruction files your tools already use — `AGENTS.md`, `CLAUDE.md`, Copilot, Cursor, Windsurf, Gemini — writes a short block into each one naming the path to the rules that ship inside the package, and prints back which files it touched. It points rather than copies, so it cannot overwrite rules you wrote yourself, and upgrading the library upgrades what your assistant reads.
Skipping this changes nothing about how the library works, only how much your assistant gets right first time. The [CLI reference](https://www.theui.dev/docs/cli) covers every option, and [AI coding assistants](https://www.theui.dev/docs/ai-assistants) covers what the rules actually say.
## Your First Component
Components are named exports of `theui-svelte`, so you import the ones you use and nothing else. Drop this into a page to see that everything is wired up: the button raises a notification, which means the components, the styles and the store are all working.
**+page.svelte**
```svelte
```
Two more entry points come with the package: `theui-svelte/type` for the [TypeScript types](https://www.theui.dev/docs/types), and `theui-svelte/function` for helpers such as `notify` and `sanitize`.
## Dark Mode
Dark mode is driven by a `dark` class on the `` element. The stylesheet you imported brings the variant with it, so there is nothing to add to your Tailwind setup, and every component already carries its dark styles.
Put the [`DarkMode`](https://www.theui.dev/docs/dark-mode) component somewhere in your layout and it does the rest: it follows the operating system until someone chooses for themselves, then remembers that choice.
## Upgrading From Version 2
Version 3 is a break with version 2. These are the changes most likely to touch your code:
- Svelte 5.57.1 or newer and Node.js 22.12 or newer are required.
- The brand colors were renamed: `brand-primary-50` ... `brand-primary-950` are now `brand-50` ... `brand-950`, and `text-on-brand-primary` is now `text-on-brand`. Rename them in your markup, and rename `--color-brand-primary-*` and `--text-color-on-brand-primary` if you overrode them.
- The second brand color is gone. `brand-secondary-*` and `text-on-brand-secondary` no longer exist; use any Tailwind color, or one of your own, in their place.
- The raw surface values are prefixed now: `--light1` ... `--dark3` are `--theui-light1` ... `--theui-dark3`. This only matters if you overrode them; `bg-primary`, `bg-secondary` and `bg-tertiary` are unchanged.
- String props such as `helperText`, a `title` or a `label` render as plain text now. Pass a snippet, or write the content inside the component, where you used to pass markup.
- `Tab` and `TabPanel` each need a `value`, and a tab opens the panel that carries the same one.
- `Toggle` uses `checked` for a checkbox and `group` for a radio; `value` is now only the value of the input.
- The `reverse` attribute of `Checkbox`, `Radio` and `Toggle` is now `labelPosition`.
- `Button`, `QabItem` and `NavBrand` no longer invent an `aria-label`, so give icon-only controls an `ariaLabel` of your own.
- The `position` setting of `notify()` moved to the `position` prop of the `Notification` component.
- `style.css` no longer loads `@tailwindcss/typography`.
The changelog in the [GitHub repository](https://github.com/mbparvezme/theui-svelte) lists every change, including the rewritten `Slider` and the new components.
---
Category: Guides
Keywords: installation, setup, guide, theui-svelte, svelte, component-library
Full documentation set: https://www.theui.dev/llms-full.txt