Web Components 1.0.1

Web components for developing Riverty experiences.

View on NPM. View on riverty.design.

Introduction and usage guidelines

Two things need to be in place in order for the Riverty web components to function:

1. The @riverty/web-components loader script. This enables all supported components and includes automatic lazy loading.
2. CSS for the Riverty design tokens and fonts, best done through the @riverty/css-framework. This defines how the components are styled.

Our recommendation is to include the CSS framework and the web components globally for all pages in your Riverty website or web app. This allows you to use the design system styles, typography, and components wherever needed.

Use as NPM package

Install the packages:

npm install --save-dev @riverty/web-components @riverty/css-framework

Apply the CSS Framework as described in its documentation. For instance by importing it into your global Sass stylesheet:

@import "@riverty/css-framework/lib/riverty.css";

Then, import and apply the Web components loader in your global JavaScript:

import { defineCustomElements } from '@riverty/web-components/loader';
defineCustomElements();

After that, you a ready to use any component as needed. To verify that everything is set up correctly, you can try adding the development helper component like this:

<r-design-system-devtools design-tokens></r-design-system-devtools>

The element should render with a few text blocks in the Riverty colors.

Additional steps for Vue 3 project

Import and apply the Web components loader to main.js using applyPolyfills and defineCustomElements.

import {
  applyPolyfills,
  defineCustomElements,
} from '@riverty/web-components/loader';

applyPolyfills().then(() => defineCustomElements(window));

Modify vite.config.js adding compilerOptions and optimizeDeps.

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.includes('r-'),
        },
      },
    }),
  ],
  optimizeDeps: {
    exclude: ['@riverty/web-components/loader'],
  },
});

Other framework-specific instructions forthcoming.

Use via CDN

Instead of installing the packages and using a build tool, you can include both the CSS framework and the components directly from the web.

All CDN links can be found in riverty.design/cdn.

Inline docs and autocomplete for Visual Studio Code

The @riverty/web-components package includes a custom-elements.json file that follows VS Code’s custom data format. What does that mean? You can configure your VS Code workspace to give suggestions and inline documentation for all design system components.

At the root of a project using @riverty/web-components, add or edit the .vscode/settings.json:

"html.customData": [
  "node_modules/@riverty/web-components/custom-elements.json"
]

Event handling

Many components emit custom events to let you follow user interactions. Custom events docs on riverty.design.