Configuration

Configure Catnip components at app init: type conversion, form behaviour, i18n, and test attributes.

A shell or single app can import named APIs from @signicat/catnip-components. A micro-frontend remote must not import a second copy — after the shell has mounted Catnip, use window.Catnip:

window.Catnip.version; // shell’s `@signicat/catnip-components` version
window.Catnip.registerTranslate((key) => i18n.global.t(key));
window.Catnip.configure({ automaticTypeConversion: true });
const value = window.Catnip.parseEmitDetail(event);

CatnipConfig

import { CatnipConfig } from "@signicat/catnip-components";

CatnipConfig.configure({
  automaticTypeConversion: true,
  nativeFormBehaviour: true,
  nativeFormValidation: false
});

Equivalent after mount: window.Catnip.configure({ … }).

Options

Option	Default	Description
automaticTypeConversion	true	Auto-convert string attributes (e.g. size="48") to JS types
nativeFormBehaviour	true	Form elements participate in native form submit/value sync
nativeFormValidation	false	Enable native HTML5 validation (requires nativeFormBehaviour)
registerTranslate	built-in	Override for i18n — pass your translation function (see Internationalization)
locale	built-in	Override for translation lookup

const config = CatnipConfig.getConfig();
CatnipConfig.reset(); // Reset to defaults

Internationalization

Components use translation keys for accessible labels where applicable. Bundle fallback: spinner.loading → "Loading...". Override via registerTranslate.

Shell / single app:

import { registerTranslate } from "@signicat/catnip-components";

registerTranslate((key) => i18n.global.t(key));

Micro-frontend remote (do not import the package):

window.Catnip.registerTranslate((key) => i18n.global.t(key));

Package entry points

• Default — @signicat/catnip-components for standard ESM/UMD

• FOUC prevention — @signicat/catnip-components/foucPrevention.min.css to hide catnip-* until styles load

• CDN standalone — catnip-components.standalone.js is built in CI and hosted on the CDN; it is not published on npm. See Installation — CDN.

See Installation — npm entry points for details.

CDN

The standalone script publishes window.Catnip (first write wins). Prefer that in remotes. Named exports also hang on CatnipComponents (same instance, not a second library):

<script src="https://static.signicat.com/catnip/components/latest/catnip-components.standalone.js" defer></script>
<script>
  window.Catnip.configure({
    automaticTypeConversion: true,
    nativeFormBehaviour: true
  });

  window.Catnip.registerTranslate((key) => myTranslations[key] ?? key);
</script>

If you use the ES build on CDN with an import map, a shell may import { CatnipConfig } in a module script — remotes should still use window.Catnip. See Installation — CDN configuration.

Test attributes

All components support a testSelectors prop for stable test automation. It maps internal element keys (e.g. root, anchor, content) to data-test values. Each component has defaults; you can override or extend them per instance:

<catnip-tooltip .testSelectors='{"root":"my-tooltip","content":"my-tooltip-body"}'>
  Help text
</catnip-tooltip>

• Object: { root: "my-icon", … } — override specific keys. Unlisted keys keep their defaults.
• String: JSON string for attribute-based usage, e.g. test-selectors='{"root":"my-icon"}'.

Nested objects may be forwarded into embedded Catnip children on composed hosts; see Component API — Test selectors (including Multiple subcomponents of the same type).

Each component lists its default test selectors and keys in the Test Selectors section of its page. For a focused guide, see Component API — Test selectors.