Getting Started

Pacem JS ships as a set of scoped npm packages. Install the all-in-one bundle if you want everything:

> npm install @pacem/pacem

...or install only the capabilities you need - every package depends on @pacem/pacem-foundation and @pacem/pacem-core internally, so npm pulls those in automatically:

> npm install @pacem/pacem-foundation @pacem/pacem-core @pacem/pacem-ui

Either way you end up with the exact same files on disk; the bundle is just a convenience that re-exports every package under one dependency. From here you can consume Pacem JS without a bundler, via plain <script> tags, or with one, via ES module imports.

Plain <script> tags

Each package ships a self-contained, minified script that extends a shared window.Pacem global. Load pacem-foundation first, then pacem-core, then whichever component packages you need - later scripts extend the same global object, so order matters.

<!-- from the bundle: node_modules/@pacem/pacem/dist/browser/ -->
<script src="/node_modules/@pacem/pacem/dist/browser/pacem-foundation.min.js"></script>
<script src="/node_modules/@pacem/pacem/dist/browser/pacem-core.min.js"></script>
<script src="/node_modules/@pacem/pacem/dist/browser/pacem-ui.min.js"></script>
<script src="/node_modules/@pacem/pacem/dist/browser/pacem-scaffolding.min.js"></script>

<!-- from single packages: same files, one node_modules folder per package -->
<script src="/node_modules/@pacem/pacem-foundation/dist/browser/pacem-foundation.min.js"></script>
<script src="/node_modules/@pacem/pacem-core/dist/browser/pacem-core.min.js"></script>
<script src="/node_modules/@pacem/pacem-ui/dist/browser/pacem-ui.min.js"></script>
<script src="/node_modules/@pacem/pacem-scaffolding/dist/browser/pacem-scaffolding.min.js"></script>

Once loaded, custom elements like <pacem-button> or <pacem-form> just work in markup - no customElements.define calls needed on your end.

ES modules

If your build already goes through a bundler (rollup, webpack, vite, esbuild...), import from the bundle:

import { Components } from '@pacem/pacem';

const { PacemElement, UI } = Components;
const { PacemButtonElement } = UI;

or from single packages, which keeps your own bundle smaller by only pulling in what you actually import:

import { Components as CoreComponents } from '@pacem/pacem-core';
import { Components as UiComponents } from '@pacem/pacem-ui';

const { PacemElement } = CoreComponents;
const { PacemButtonElement } = UiComponents;

Either form also registers the custom elements as a side effect of importing, exactly like the <script> tags above.

Styling

Pacem JS doesn't ship one fixed CSS file: themes are generated, not hand-picked. A small JSON palette (a handful of named seed colors) gets expanded into a full WCAG-contrast-aware LESS palette by @pacem/pacem-theme-less's themebuilder.js, then compiled to CSS with lessc. See the Theme section for the generated result, and this site's own build for a working example of the palette → LESS → CSS pipeline.

CustomElements

Pacem JS provides a collection of already defined webcomponents, nevertheless it allows you, the developer, to build your own.
Create your class and add a @CustomElement decoration:

@CustomElement({ tagName: 'my-custom' })
export class MyCustomElement extends HTMLElement{
}

You can take advantage of some basic functionalities by extending classes other than HTMLElement directly:

• PacemEventTarget: this class provides core event emitting capabilities (triggers the on-<event> declarative handlers) alongside with disabled state management. It is generally meant to be extended by non-UI elements.
• PacemElement: it extends PacemEventTarget and adds UI capabilities like css, css-class, tooltip, behaviors and others...

Lifecycle

The connectedCallback() method gets called and the isConnected flag is set to true.
Bindings do not get processed yet: a preliminary check is done about the overall DOM state ("completely loaded or not?").

The first propertychange event might be fired due to (either):

• declaratively assigned attribute on the DOM element,
• non-null default value assigned to the watched property.

The propertyChangedCallback() method gets hit with a true value for the 'firstChange' parameter (the 4th parameter in the method signature).
You cannot assume to safely access the sub-DOM of the web component when managing this change.

The custom (Pacem JS-specific) viewActivatedCallback() method gets called and the (also custom) isReady flag is set to true.
Bindings do get processed: the overall DOM state is ready and the template of the component has been applied.

The element fires the load event.

"Property change" generally occurs many times during the lifespan of the webcomponent.
The propertyChangedCallback() method gets hit with a false value for the 'firstChange' parameter (the 4th parameter in the method signature).
You can assume to safely access the sub-DOM of the web component when managing this change.

When the element is removed from the DOM, the disconnectedCallback() method gets called and both the isConnected and isReady flags are set to false.

This is the ideal hook for listeners and resources disposure.

The element fires the unload event.