@synergy-design-system/components

This package provides the base of the Synergy Design System as native web components.
It uses lit and parts of shoelace. Synergy officially supports the latest two versions of all major browsers (as defined by browserslist) and is actively linted and integration tested against those targets.

Known issues and limitations

Got any problems using our components? Please take a look at our list of known issues and limitations before creating a ticket.

Getting started

$3

If you want to see a usage example, please check out our test Web Components repository.

$3

Run the following steps to install the required packages.

``bash


Install the base library

npm install --save @synergy-design-system/components

Install the required design tokens

(only needed if you do not install peerDeps automatically)

npm install --save @synergy-design-system/tokens

Optional: Install the styles utility package

npm install --save @synergy-design-system/styles

Optional: if icons shall be used, install the assets package

npm install --save @synergy-design-system/assets
`

---

$3

The shipped components make heavy use of design tokens, which are provided via @synergy-design-system/tokens. Make sure to follow the installation steps there for help on setting the tokens up. Usually it is enough to load the light or dark theme included there.

This package also comes with css utilities that are required to make synergy work.
You may either load all of them in one bundle (recommended) or just include the bits that you need.

> When loading custom bits, please make sure to always include dist/styles/utility.css!
> Without these utilities, fullscreen components will not work as intended!

##### List of available css utilities

| Utility | Required? | Path | Description |
| :------ | :-------: | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| fouc | | dist/styles/fouc.css | Defaults for handling Flash of Undefined Components (FOUC). Scoped to only target Synergy Components to make sure it does not overlap with other custom elements already defined. |
| utility | ✔ | dist/styles/utility.css | Utilities that have to be in the light DOM to make Synergy work. For example, these include scroll locking for fullscreen components. This is required, your application layout may break if not available! |

##### 2.1. Loading all css utilities (recommended)

`html





rel="stylesheet"
src="../node_modules/@synergy-design-system/components/dist/styles/index.css"
/>



`

##### 2.2. Load only parts of the utilities

`html





rel="stylesheet"
src="../node_modules/@synergy-design-system/components/dist/styles/utility.css"
/>



`

---

$3

There are multiple ways to load the components:

#### Loading all available components

To make all components available, just load the main package file. It will make sure that all components and needed dependencies are loaded and available directly.

> Please keep in mind that this way of loading the components will create larger bundle sizes!

`html











type="module"
src="../node_modules/@synergy-design-system/components/dist/synergy.js"
>


`

When using a build system, you should load the bundle in JavaScript or TypeScript directly, for example when using vite:

`typescript
// main.ts

// Do not forget to load the design tokens!
import "@synergy-design-system/tokens/themes/light.css";

// Add the css utility functions.
import "@synergy-design-system/components/index.css";

// This will load synergy.js via the exports map
import "@synergy-design-system/components";
`

#### Loading selected components only

Use this when you need complete control about which components are loaded. This will usually lead to smaller bundle sizes, which might be preferable for your application. As a downside, you will have to remember adding missing components to your bundle.

`html











type="module"
src="../node_modules/@synergy-design-system/components/dist/components/button/button.js"
>


`

When using a build system, you may also load the bundle in JavaScript or TypeScript directly, for example when using vite:

`typescript
// main.ts

// Do not forget to load the design tokens!
import "@synergy-design-system/tokens/themes/light.css";

// Add the css utility functions.
import "@synergy-design-system/components/index.css";

// This will only load and define the button itself
import "@synergy-design-system/components/components/button/button.js";
`

---

$3

The components are built using typescript and provide types for elements and events out of the box. These can be used for working with the dom when working in a typescript environment. You may use them by importing the needed types and using them for elements, like shown in this example:

`typescript
// main.ts

// Do not forget to load the design tokens!
import "@synergy-design-system/tokens/themes/light.css";

// Example 1: Load the type for syn-button from the root:
import type {
SynButton,
SynInvalidEvent,
} from "@synergy-design-system/components";

// Example 2: Load the type from the syn-button dir directly.
// In this case you will have to load the event type from another file!
import type { SynButton } from "@synergy-design-system/components/components/button/button.component";
import type { SynInvalidEvent } from "@synergy-design-system/components/events/events";

document.addEventListener("load", () => {
const loadedSynButtons = document.querySelectorAll("syn-button");

// Attach a syn-invalid event that is fired every time a button becomes invalid
Array.from(loadedSynButtons) // Type: SynButton[]
.addEventListener("syn-invalid", (e: SynInvalidEvent) => {
console.log("Button is now invalid!", e);
});
});
`

---

$3

This package ships with a custom-elements-manifest that may be used to provide typings for tags. To enable code completion, please proceed the following way:

1. Install the @synergy-design-system/components package.
2. If you do not have a .vscode/settings.json file yet, create it.
3. Add support for vscode-custom-data by adding the following setting to your .vscode/settings.json: "html.customData": ["./node_modules/@synergy-design-system/components/dist/vscode.html-custom-data.json"]
4. Restart VSCode.
5. Switch to an html (or similar) file and type . Auto-complete now provides a list of available components along with its attributes.

> Note the path above is valid for installations using npm.
> When using another package manager, make sure to set the proper path to vscode.html-custom-data.json`!

---

$3

Please have a look at the official breaking changes list for information how to update to new major versions of Synergy.

---