# Installation
Rails Blocks lets you add individual components to your Rails 7+ application by copying the code into your app. This gives you full control over the markup, styles, and Stimulus behavior.
## 1. Dependencies
Rails Blocks is built with Tailwind CSS v4+ and Stimulus. Install those first with Importmap, NPM, or Yarn, then add the optional libraries used by the full component set.
### Importmap
Add this to `config/importmap.rb`:
```ruby
pin "@floating-ui/dom", to: "https://cdn.jsdelivr.net/npm/@floating-ui/dom@1.7.6/+esm"
pin "number-flow", to: "https://esm.sh/number-flow"
pin "number-flow/group", to: "https://esm.sh/number-flow/group"
pin "embla-carousel", to: "https://cdn.jsdelivr.net/npm/embla-carousel/embla-carousel.esm.js"
pin "embla-carousel-wheel-gestures", to: "https://cdn.jsdelivr.net/npm/embla-carousel-wheel-gestures@latest/+esm"
pin "tom-select", to: "https://cdn.jsdelivr.net/npm/tom-select@2.5.2/+esm"
pin "air-datepicker", to: "https://esm.sh/air-datepicker@3.6.0"
pin "air-datepicker/locale/en", to: "https://esm.sh/air-datepicker@3.6.0/locale/en"
pin "emoji-mart", to: "https://cdn.jsdelivr.net/npm/emoji-mart@latest/dist/browser.js"
pin "photoswipe", to: "https://cdn.jsdelivr.net/npm/photoswipe/dist/photoswipe.esm.js"
pin "motion", to: "https://cdn.jsdelivr.net/npm/motion@latest/+esm"
```
### NPM
```bash
npm install @floating-ui/dom number-flow embla-carousel embla-carousel-wheel-gestures tom-select air-datepicker emoji-mart photoswipe motion
```
### Yarn
```bash
yarn add @floating-ui/dom number-flow embla-carousel embla-carousel-wheel-gestures tom-select air-datepicker emoji-mart photoswipe motion
```
Add these stylesheet and script tags to your application `<head>`:
```erb
<!-- Shoelace -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.1/cdn/components/color-picker/color-picker.js"></script>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.1/cdn/themes/light.css"
/>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.20.1/cdn/themes/dark.css"
/>
<!-- Tom Select -->
<link href="https://cdn.jsdelivr.net/npm/tom-select@2.5.2/dist/css/tom-select.css" rel="stylesheet">
<!-- Air Datepicker -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/air-datepicker@3.6.0/air-datepicker.min.css">
<!-- Photoswipe -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/photoswipe/dist/photoswipe.css">
```
## 2. Stimulus Controllers
Configure `app/javascript/controllers/index.js` so Rails can load component controllers automatically:
```javascript
// Import and register all your controllers from the importmap under controllers/*
import { application } from "controllers/application";
// Eager load all controllers defined in the import map under controllers/**/*_controller
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading";
eagerLoadControllersFrom("controllers", application);
```
Also make sure `config/importmap.rb` includes:
```ruby
# Make sure these lines are in your importmap:
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"
pin_all_from "app/javascript/controllers", under: "controllers"
```
Download the controller ZIP from the HTML installation page:
- Free controllers: `/downloads/stimulus_controllers?type=free`
- Pro controllers: `/downloads/stimulus_controllers?type=pro`
After downloading, unzip the file and copy the contents to `app/javascript/controllers/`.
If you have the Rails Blocks CLI installed, you can also install component Stimulus controllers with the CLI. See the CLI install docs: `/docs/cli#install-the-cli`.
## 3. Custom CSS
Copy the free Rails Blocks CSS into your main CSS file, usually `app/assets/stylesheets/application.css` or your Tailwind entry file.
The full CSS is available as a dedicated Markdown page so LLMs can load it only when needed:
- Current access CSS: `/docs/installation/custom-css.md`
- Free CSS: `/docs/installation/custom-css-free.md`
Load one of those pages directly when you need to copy the entire CSS block.