Getting started

Diffix Web Components is a modern, performant, customizable, open-source UI library. Provides a set of reusable components to build web applications with consistent user experience.

• Build a modern, highly performant, and highly accessible web experience.
• Integrate with any JavaScript framework such as React, Vue, Angular, Svelte, etc.
• Build a standards-based user interface following W3C Web Component standards.
• Customize the design language for your project by modifying design tokens.
• Use the components out-of-the-box in existing front-end projects.

Instalation

Ensure you have the latest Node.js installed on your machine. Use a package manager to install Diffix from npm:

npm install diffix

Import components

Import the target component from diffix/components/component-name. Import automatically registers the Web Component (causes a side effect).

import 'diffix/components/button';

Or you can import all components at once:

import 'diffix';

Import theme

To use the default theme, import the CSS file. There are two ways to do this:

1. Using an application bundler (Webpack, Rollup, Vite, etc.):

import 'diffix/themes/default.css';

2. Or using a <link> tag:

<link href="/node_modules/diffix/dist/themes/default.css" rel="stylesheet" />

Usage

Diffix components are designed to be used as Web Components. This means you import the target component in the script and then use it in the HTML.

<dfx-button theme="primary" variant="filled">Button</dfx-button>

Form controls should be automatically detectable inside the <form> element. You can use the FormData to serialize data from the form. Client-side validation uses Constraint Validation API. You can activate it using attributes such as required, minLength, maxLength, pattern, etc. If you want to disable the browser validation bubble, use the novalidate attribute on the <form> element.

<form id="form" novalidate>
  <dfx-input label="Name" name="name" required></dfx-input>
  <dfx-button type="submit" variant="filled">Submit</dfx-button>
</form>

<script>
  document.querySelector('#form').addEventListener('submit', event => {
    event.preventDefault();
    if (event.target.checkValidity()) {
      const formData = new FormData(event.target);
      alert(JSON.stringify(Object.fromEntries(formData)));
    }
  });
</script>

Components are published as ES modules so that they can be used in all modern browsers with no build step. That's good for prototyping, but for performance reasons, components in production should be bundled, tree-shaken, and optimized by individual applications using bundlers like Webpack, Rollup, or Vite.

There is a simple demo using Vite to showcase the usage of individual components.

Attribution

Special thanks to the following projects that help make this project possible:

• Components are built with Lit, Vite, and TypeScript.
• Component tests run on Web Test Runner and Playwright.
• Documentation is built with Storybook and hosted on Netlify.
• Components are linted with ESLint and formatted with Prettier.
• Component metadata is generated by Custom Elements Manifest.
• Commits are linted with Commitlint and formatted with Commitizen.
• Components are published to npm with Semantic Release.

Contribute

As an open-source project, all contributions are welcome! Feel free to report bugs and submit feature requests. Please read the Contributing Guide if you want to contribute to the code.

License

Diffix was created by Dominik Fryč. It's available under the MIT license. You can use it in any project, commercial or not, with or without attribution.