---
url: https://ambiki.github.io/impulse_view_components/introduction/getting-started.md
---
# Getting started

## Requirements

* Ruby 3.4 or later, and Rails 7.1 or later.
* [Bootstrap 4](https://getbootstrap.com/docs/4.6/)'s CSS. The components use its classes, such as `form-control`,
  `dropdown-menu`, `btn` and `spinner-border`.
* [Bootstrap Icons](https://icons.getbootstrap.com/)' CSS, for the icons the components render, such as `bi-x`.
* [Dart Sass](https://sass-lang.com/dart-sass/), if you compile the components' Sass.

## Install the gem

Add the gem to your `Gemfile`:

```rb
gem "impulse_view_components"
```

Then install it:

```bash
bundle install
```

## Require the engine

Require the engine in `config/application.rb`:

```rb
require "impulse/view_components/engine"
```

## Install the JavaScript package

The interactive components ship as custom elements, so you also need the npm package. It's built on
[`@ambiki/impulse`](https://github.com/Ambiki/impulse) 2, which you install alongside it, so your own elements and the
components share one copy:

```bash
yarn add @ambiki/impulse-view-components @ambiki/impulse
```

## Import the components

Each component is imported individually, so you only ship what you use.
For example, to use the [Select](/components/select) component:

```js
import '@ambiki/impulse-view-components/autocomplete';
```

To register every component at once, import the package itself:

```js
import '@ambiki/impulse-view-components';
```

See the **Imports** section on each component's page for the exact paths.

## Import the styles

The styles are written in Sass on top of [Bootstrap 4](https://getbootstrap.com/docs/4.6/). Load Bootstrap's Sass
functions, variables and mixins first (importing all of `bootstrap` does that), then the base styles once, then each
component's styles:

```scss
@import 'bootstrap/scss/functions';
@import 'bootstrap/scss/variables';
@import 'bootstrap/scss/mixins';

@import '@ambiki/impulse-view-components/base';
@import '@ambiki/impulse-view-components/autocomplete';
```

To include every component's styles, import the package itself instead of `base` and each component:

```scss
@import 'bootstrap/scss/functions';
@import 'bootstrap/scss/variables';
@import 'bootstrap/scss/mixins';

@import '@ambiki/impulse-view-components';
```

These paths work through webpack's `sass-loader` and Vite. When you run the `sass` command line directly, as
`cssbundling-rails` does, prefix each path with `pkg:` and pass `--pkg-importer=node`, which needs Dart Sass 1.71 or
later:

```scss
@import 'pkg:@ambiki/impulse-view-components/base';
@import 'pkg:@ambiki/impulse-view-components/autocomplete';
```

A setup that only passes `--load-path=node_modules` can't read these paths, because it looks for files rather than
reading the package's `exports`. It can keep importing the files directly:

```scss
@import '@ambiki/impulse-view-components/dist/styles/variables';
@import '@ambiki/impulse-view-components/dist/styles/base';
@import '@ambiki/impulse-view-components/dist/elements/autocomplete';
```

### Without Sass

If your app doesn't compile Sass, import the precompiled CSS, which holds every component's styles:

```js
import '@ambiki/impulse-view-components/styles.css';
```

It's built with Bootstrap's default variables, and doesn't include Bootstrap's component CSS, which you still load. Change
colors and sizes through the CSS custom properties it defines
on `:root`, such as `--awc-autocomplete-control-min-height`.

## Upgrading from `dist/` paths

The package no longer exports paths that start with `@ambiki/impulse-view-components/dist/`. Use the shorter paths
below.

| Removed path                                                     | Use instead                                                                    |
|------------------------------------------------------------------|--------------------------------------------------------------------------------|
| `…/dist/index.js`                                                | `@ambiki/impulse-view-components`                                              |
| `…/dist/elements/<name>`, `…/dist/elements/<name>/index.js`      | `@ambiki/impulse-view-components/<name>`, such as `…/popover`                  |
| `import useFloatingUI from '…/dist/hooks/use_floating_ui'`       | `import { useFloatingUI } from '@ambiki/impulse-view-components/hooks'`        |
| `import useOutsideClick from '…/dist/hooks/use_outside_click'`   | `import { useOutsideClick } from '@ambiki/impulse-view-components/hooks'`      |
| `import useFocusOut from '…/dist/hooks/use_focus_out'`           | `import { useFocusOut } from '@ambiki/impulse-view-components/hooks'`          |
| `@import '~…/dist/elements/<name>'`                              | `@import '@ambiki/impulse-view-components/<name>'`                             |
| `@import '~…/dist/styles/variables'` and `'~…/dist/styles/base'` | `@import '@ambiki/impulse-view-components/base'`                               |
| `import { cycle } from '…/dist/helpers/array'`                   | `import { cycle } from '@ambiki/impulse-view-components/helpers'`              |
| `import debounce from '…/dist/helpers/debounce'`                 | `import { debounce } from '@ambiki/impulse-view-components/helpers'`           |
| `import scrollLock from '…/dist/helpers/scroll_lock'`            | `import { scrollLock } from '@ambiki/impulse-view-components/helpers'`         |
| Any other `…/dist/helpers/*`, or `…/dist/elements/autocomplete/<module>` such as `ajax_search` | None. These modules are internal. |

The Sass rows need a setup that reads the package's `exports`. A setup that only passes `--load-path` keeps importing
the files, as [Import the styles](#import-the-styles) shows.

Each element path exports its class by name, such as `AwcPopoverElement`, along with the types its properties use.
`…/hooks` exports the types the hooks take and return, and `…/helpers` the [helpers](/helpers/) apps can use.
