Skip to content

Getting started ​

Requirements ​

  • Ruby 3.4 or later, and Rails 7.1 or later.
  • Bootstrap 4's CSS. The components use its classes, such as form-control, dropdown-menu, btn and spinner-border.
  • Bootstrap Icons' CSS, for the icons the components render, such as bi-x.
  • 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 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 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. 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 pathUse 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_searchNone. 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 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 apps can use.

Released under the MIT License.