Configuration Guides - jig - Angular Control Library by awdlab

Configuration

Everything provideJigControls accepts, in one place. The first argument is a config object; every following argument is an opt-in feature.

provideJigControls(config, ...features);

Only the config is required, and within it only theme.preset really matters — everything else has a working default.

Config reference

provideJigControls({
  logLevel: 'info',
  disableAnimations: false,
  respectReducedMotion: true,
  customTranslations: { fr: () => import('./i18n/fr').then(m => m.fr) },
  theme: {
    preset: nova,
    lazyLoaded: false,
    styleScope: null,
    cssLayer: 'jig',
    namePrefix: 'jig-',
  },
  defaults: {
    stateStorage: 'session',
    splitter: { stateStorage: 'session' },
    inputField: { showRequiredMarker: false },
    tooltip: {/* … */},
  },
});

Top level

Option	Type	Default	Description
`logLevel`	`'debug' \| 'info' \| 'warn' \| 'error'`	`'info'`	How much the library logs. Raise it to `'warn'` in production to silence informational output.
`disableAnimations`	`boolean`	`false`	Turns off control animations globally; if the OS also reports reduced motion, the reduced-motion tiers take precedence for loading indicators. See Animations.
`respectReducedMotion`	`boolean`	`true`	Reduces control animations while the OS reports `prefers-reduced-motion: reduce` — one-shot animations collapse, loading indicators slow, decorative loops stop. See Animations.
`customTranslations`	`Record<string, () => Promise<Translations>>`	—	Extra languages, loaded on demand. See i18n.

`theme`

Option	Type	Default	Description
`preset`	`Theme \| null`	`null`	The theme object (not a name). Required unless `lazyLoaded` is `true` — without one, controls throw.
`lazyLoaded`	`boolean`	`false`	Suppresses the "no theme" error, for apps that install a theme later at runtime.
`styleScope`	`StyleScope \| null`	`null`	Selector the token declarations are scoped to. `null` means `:root`. See Styling & Overrides.
`cssLayer`	`string \| null`	`'jig'`	Wraps all generated CSS in a `@layer` of this name. Set to `null` to emit unlayered CSS.
`namePrefix`	`string`	`'jig-'`	Prefix for generated class names and CSS custom properties.

cssLayer is the lever for specificity. Everything the theme emits sits in one cascade layer, so any unlayered CSS of yours wins over it regardless of selector strength — no !important, no ::ng-deep.

styleScope takes a selector descriptor rather than a raw string:

styleScope: { kind: 'class', name: 'my-app' } // .my-app { --jig-…: … }
styleScope: { kind: 'attribute', name: 'data-jig', value: 'on' }
styleScope: { kind: 'id', name: 'app-root' }
styleScope: { kind: 'tag', name: 'my-app' }

Use it to keep the design tokens off :root when the library lives inside a larger page you do not own.

`defaults`

Option	Type	Default	Description
`stateStorage`	`'local' \| 'session'`	`'session'`	Where controls persist UI state. See State Persistence.
`splitter.stateStorage`	`'local' \| 'session'`	inherits `stateStorage`	Per-control override for the splitter.
`inputField.showRequiredMarker`	`boolean`	`false`	Mark the label of every input field whose control is required. Override per field with `[showRequiredMarker]`.
`tooltip`	`TooltipOptions`	see below	Default options for every `jigTooltip`.

Tooltip defaults:

Option	Default
`placement`	`'bottom'`
`offset`	`4`
`showDelay`	`'0.5s'`
`hideDelay`	`'0.1s'`
`showArrow`	`true`
`showOnHover`	`true`
`showOnFocus`	`true`
`hideOnTooltipHover`	`false`
`hideOnClick`	`true`
`autoAriaMode`	`'description'`

Any of these can still be overridden per tooltip.

Features

Each with*() is opt-in — leave it out and none of its code ships.

Feature	From	Enables
`withDefaultIcons()`	`@awdlab/jig/default-icons`	The built-in Tabler icon set for all semantic slots.
`withCustomIcons(registry)`	`@awdlab/jig/icon`	Your own icon set. See Icons.
`withAutoColorScheme(options?)`	`@awdlab/jig/api/ng`	Automatic light/dark switching. See Dark Mode.
`withToasts(defaults?)`	`@awdlab/jig/toast`	The toast service and host.
`withSnackbars(defaults?)`	`@awdlab/jig/snackbar`	The snackbar service and host.

A control that needs a feature you did not register fails loudly — an icon slot with no registry throws at render, and the toast/snackbar managers throw when injected without their feature.

A complete setup

import { ApplicationConfig } from '@angular/core';
import { provideJigControls, withAutoColorScheme } from '@awdlab/jig/api/ng';
import { withDefaultIcons } from '@awdlab/jig/default-icons';
import { withSnackbars } from '@awdlab/jig/snackbar';
import { withToasts } from '@awdlab/jig/toast';
import { provideJigErrorsMessages } from '@awdlab/jig/errors';
import { nova } from '@awdlab/jig-themes/nova';

export const appConfig: ApplicationConfig = {
  providers: [
    provideJigControls(
      {
        logLevel: 'warn',
        theme: { preset: nova, cssLayer: 'jig' },
        defaults: { stateStorage: 'local' },
      },
      withDefaultIcons(),
      withAutoColorScheme(),
      withToasts(),
      withSnackbars()
    ),
    provideJigErrorsMessages({ required: 'This field is required.' }),
  ],
};

Reading the config

JIG_CONFIG is an injection token holding the resolved config, useful when you build your own control on top of the library:

const config = inject(JIG_CONFIG);
config.theme.namePrefix; // 'jig-'