@synergy-design-system/components

v3.15.0

Published

4 days ago

This package provides the base of the Synergy Design System as native web components. It uses [lit](https://www.lit.dev) and parts of [shoelace](https://shoelace.style/). Synergy officially supports browsers flagged as `baseline widely available` (as defi

0High
0Medium
0Low

schilchsickag

kirchsusickag

klaarse_sickag

Web Components LIT Components Design System SDS Synergy Design System SICK SICK Design System

@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 browsers flagged as baseline widely available (as defined by browserslist during major releases) 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

1. Usage example

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

2. Package installation

Run the following steps to install the required packages.

# 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. Load the desired theme (required) and utility classes (recommended)

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)

<!-- Example 1: Loading all utility functions -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link
      rel="stylesheet"
      src="../node_modules/@synergy-design-system/components/dist/styles/index.css"
    />
  </head>
  <body></body>
</html>

2.2. Load only parts of the utilities

<!-- Example 2: Loading only the required utility functions -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link
      rel="stylesheet"
      src="../node_modules/@synergy-design-system/components/dist/styles/utility.css"
    />
  </head>
  <body></body>
</html>

4. Importing and rendering components

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!

<!-- Example 1: Loading via script type module -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
  </head>
  <body>
    <div id="root">
      <syn-button variant="text">Button</syn-button>
      <syn-input></syn-input>
    </div>
    <!-- As we are loading all modules, syn-button and syn-input will render correctly -->
    <script
      type="module"
      src="../node_modules/@synergy-design-system/components/dist/synergy.js"
    ></script>
  </body>
</html>

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

// 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.

<!-- Example 1: Loading via script type module -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
  </head>
  <body>
    <div id="root">
      <syn-button variant="text">Button</syn-button>
      <syn-input></syn-input>
    </div>
    <!-- We are only loading the button, syn-input will render as an empty div! -->
    <script
      type="module"
      src="../node_modules/@synergy-design-system/components/dist/components/button/button.js"
    ></script>
  </body>
</html>

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

// 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";

5. Using the provided types

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:

// 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<SynButton>("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);
    });
});

6. Using the `syn-chart` component (optional)

For more detailed information about the syn-chart component see the Charting Overview page

The <syn-chart> component allows you to display charts powered by Apache ECharts. Because not every project needs charting functionality, echarts is an optional peer dependency that must be installed separately.

Note: syn-chart is currently experimental. Only line charts (series[].type: 'line') are supported. Support for additional chart types will be added in future releases.

Step 1: Install the `echarts` dependency

npm install --save echarts

Note: Only Apache ECharts version 6 (echarts@^6.1.0) is officially supported. Other versions may work but are not tested or guaranteed to be compatible.

Step 2: Load the component tokens (required)

The chart component requires two sets of design tokens to render correctly:

The standard Synergy component tokens – loaded as part of the regular theme setup (light or dark). If you have already done this as part of step 3 above, you can skip this.
The chart-specific tokens – must be loaded in addition to the standard tokens.

// main.ts

// 1. Load the standard Synergy theme tokens (light or dark)
import "@synergy-design-system/tokens/themes/light.css";

// 2. Load the chart-specific tokens matching your theme (light or dark)
import "@synergy-design-system/tokens/charts/themes/light.css";

Step 3: Import the chart component explicitly

syn-chart is not included in the default Synergy bundle (i.e. it is not exported by the main synergy.js entry point). You must import it explicitly:

// main.ts

// Import the chart component explicitly (not part of the default bundle)
import "@synergy-design-system/components/components/chart/chart.js";

Step 4: Use the component in your HTML

<syn-chart id="my-chart"></syn-chart>

<script type="module">
  const chart = document.getElementById("my-chart");

  chart.config = {
    xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
    yAxis: { type: "value" },
    series: [{ type: "line", data: [820, 932, 901, 934, 1290] }],
  };
</script>

Complete setup example (using a build tool like Vite)

// main.ts

// 1. Load the standard Synergy theme (required for all components)
import "@synergy-design-system/tokens/themes/light.css";

// 2. Load the chart-specific tokens (required for syn-chart)
import "@synergy-design-system/tokens/charts/themes/light.css";

// 3. Load the Synergy CSS utility functions
import "@synergy-design-system/components/index.css";

// 4. Import the chart component explicitly
import "@synergy-design-system/components/components/chart/chart.js";

For the full API documentation, available properties, and live examples, visit the syn-chart component documentation.

7. Add html autocompletion to VSCode (optional)

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:

Install the @synergy-design-system/components package.
If you do not have a .vscode/settings.json file yet, create it.
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"]
Restart VSCode.
Switch to an html (or similar) file and type <syn. 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!

8. Breaking changes between major versions

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@synergy-design-system/components

Known issues and limitations

Getting started

1. Usage example

2. Package installation

3. Load the desired theme (required) and utility classes (recommended)

List of available css utilities

2.1. Loading all css utilities (recommended)

2.2. Load only parts of the utilities

4. Importing and rendering components

Loading all available components

Loading selected components only

5. Using the provided types

6. Using the syn-chart component (optional)

Step 1: Install the echarts dependency

Step 2: Load the component tokens (required)

Step 3: Import the chart component explicitly

Step 4: Use the component in your HTML

Complete setup example (using a build tool like Vite)

7. Add html autocompletion to VSCode (optional)

8. Breaking changes between major versions

6. Using the `syn-chart` component (optional)

Step 1: Install the `echarts` dependency