LFDS Core Components

LFDS is Länsförsäkringar's design system core components distributed as composable Web Components.

Scope of this README

This README describes this package only:

• how to install and use @lansforsakringar/core-components
• how to include required styles from @lansforsakringar/core-css
• package-local tooling (bundler plugins/CLI)

For monorepo-level setup, use root README.md. For core package release/versioning operations, use packages/core/README.md.

Breaking changes and migrations

• High-level migration summary: BREAKING_CHANGES_v3.md
• Web component rename mapping: docs/migrations/web-components-rename.md
• Rename codemod: scripts/migration/rename-web-components.js

Note: API naming for components follows lfds-* / Lfds*. Some tooling identifiers in examples (for example plugin/CLI names) may still use legacy lfui naming for compatibility.

Using Components

Bundling

Install

The design system is published on npm. It has a peer dependency on lit, so you need to install both packages. This avoids shipping duplicate Lit versions in the same application and lets you control the exact Lit version in your app.

npm install @lansforsakringar/core-css @lansforsakringar/core-components lit

Import the component bundle once in your application entrypoint:

import '@lansforsakringar/core-components'

Styles

You also need to import the global styles from @lansforsakringar/core-css. These include shared CSS variables, tokens, and fonts. With build tools like Vite or Webpack, import the CSS in your JavaScript/TypeScript entrypoint:

import '@lansforsakringar/core-css/index.css'

Or in your CSS (for example with PostCSS):

@import '@lansforsakringar/core-css/index.css';

If you are not using a build tool, see Script/Link Tag or CLI.

React

The package includes a React wrapper build. To use it, install @lit/react in addition to the base dependencies:

npm install @lansforsakringar/core-css @lansforsakringar/core-components lit @lit/react

import { LfdsButton } from '@lansforsakringar/core-components/react'

export default function App() {
	return (
		<LfdsButton onLfClick={() => console.log('clicked')}>Click me</LfdsButton>
	)
}

The React wrapper generator is shared with core-recipes in ../scripts/react-wrapper.ts. After building, run npm run test:react-types and npm run test:react to verify consumer types and browser behavior. The browser checks require npx playwright install chromium firefox webkit.

Testing Helpers

The package exports optional helpers for component interaction in automated tests, including shadow DOM interactions that consumers otherwise need to reimplement. Helpers are grouped in one namespace per component, and come in pairs: get* resolves an internal element, click* acts on it.

import { lfdsAlert } from '@lansforsakringar/core-components/testing'

const alert = document.querySelector('lfds-alert')

// Trigger the same `close` event as an end-user click.
await lfdsAlert.clickCloseButton(alert)

// Or assert on the button without interacting with it.
const closeButton = await lfdsAlert.getCloseButton(alert)
expect(closeButton).toHaveAccessibleName('Stäng Felmeddelande:')

Both wait for the component to render before querying, and throw a descriptive error when the element is absent — <lfds-alert type="info-box"> renders no close button, for example.

Parts that are only shown in some states have a query* helper that returns null instead of throwing, so you can assert that something is not shown. set* helpers act like an end user, and get*Text helpers return the text a user reads, including slotted content:

import { lfdsDatePicker } from '@lansforsakringar/core-components/testing'

const picker = document.querySelector('lfds-date-picker')

await lfdsDatePicker.setDate(picker, '2026-10-15') // emits input + change
expect(await lfdsDatePicker.getLabelText(picker)).toBe('Start date')
expect(await lfdsDatePicker.queryErrorMessage(picker)).toBeNull()

Bundler plugins

The package provides plugins for popular bundlers to copy and serve component assets.

Vite

The Vite plugin copies assets to assetDir relative to Vite's output directory. During development, assets are served as if they were local public files.

// vite.config.js
import { lfui } from '@lansforsakringar/core-components/vite'

export default {
	plugins: [lfui({ assetDir: 'lfui-assets' })]
}

Webpack

The Webpack plugin copies assets to assetDir relative to Webpack's output directory.

// webpack.config.js
const LFUIPlugin = require('@lansforsakringar/core-components/webpack')

module.exports = {
	plugins: [new LFUIPlugin({ assetDir: 'lfui-assets' })]
}

On build, assets are copied to the configured assetDir in the bundler output.

Self-hosted

If you are not using a bundler or want to serve the assets in a different way, you can copy them to your web server and serve them yourself, see CLI.

Script/Link Tag

If you are not using a bundler, export the distributable files first (for example to public/lfui) and then reference them directly in HTML:

lfui export --out public/lfui

<!doctype html>
<html>
	<head>
		<script type="module" src="/lfui/main.js"></script>
		<link rel="stylesheet" href="/lfui/main.css" />
	</head>
	<body>
		<lfds-button>Click me</lfds-button>
	</body>
</html>

CLI

This package ships with a CLI for common tasks such as exporting assets.

Export

The export command copies the distributable Lit build (main.js, main.css, related assets, and types) to a directory of your choice.

$ lfui export --out dist/lfui

Assuming the dist folder is publicly accessible on your server, reference the files like this:

<!doctype html>
<html>
	<head>
		<script type="module" src="/lfui/main.js"></script>
		<link rel="stylesheet" href="/lfui/main.css" />
	</head>
	<body>
		<lfds-button>Click me</lfds-button>
	</body>
</html>

Authoring Components in This Package

If you are building or modifying components here, start with these docs in the repo root:

• docs/components-authoring.md — How we structure, style, and wire components (what and why).
• docs/your-first-component.md — Step-by-step tutorial with full code.
• docs/component-checklist.md — Minimal PR-ready checklist.