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,btnandspinner-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:
gem "impulse_view_components"Then install it:
bundle installRequire the engine
Require the engine in config/application.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:
yarn add @ambiki/impulse-view-components @ambiki/impulseImport the components
Each component is imported individually, so you only ship what you use. For example, to use the Select component:
import '@ambiki/impulse-view-components/autocomplete';To register every component at once, import the package itself:
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:
@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:
@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:
@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:
@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:
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 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.