@cumulus-ui/components

Web Components inspired by Cloudscape Design System, built with Lit 3 and TypeScript.

Overview

Cumulus UI is a library of 90+ web components that implement the AWS Cloudscape Design System as native custom elements. Every component uses Shadow DOM for style encapsulation, works with any framework (or none), and ships as standard ES modules.

The project generates its styles and TypeScript interfaces directly from @cloudscape-design/components, so visual fidelity stays in sync with the upstream React library. You get the same look and feel without the React dependency.

Installation

npm install @cumulus-ui/components

For CDN usage (bundles Lit and all dependencies):

<script type="module" src="https://unpkg.com/@cumulus-ui/components/dist/cumulus-ui.cdn.js"></script>

Quick Start

<script type="module">
  import '@cumulus-ui/components';
</script>

<cs-button variant="primary">Save</cs-button>
<cs-input placeholder="Search..."></cs-input>
<cs-checkbox checked>Enable notifications</cs-checkbox>

All components self-register their custom element tags on import. Just import the package and start using the <cs-*> tags.

Components

See the full list at cumulus-ui.github.io/components.

Framework Integration

Vanilla HTML / CDN

<script type="module" src="https://unpkg.com/@cumulus-ui/components/dist/cumulus-ui.cdn.js"></script>

<cs-button variant="primary" onclick="alert('clicked')">Click me</cs-button>

React (via @lit/react)

import { createComponent } from '@lit/react';
import { CsButton } from '@cumulus-ui/components';
import React from 'react';

const Button = createComponent({
  tagName: 'cs-button',
  elementClass: CsButton,
  react: React,
  events: {
    onClick: 'click',
  },
});

export default function App() {
  return <Button variant="primary">Save</Button>;
}

Vue

<template>
  <cs-button variant="primary" @click="handleClick">Save</cs-button>
</template>

<script setup>
import '@cumulus-ui/components';

function handleClick() {
  console.log('clicked');
}
</script>

Vue recognizes custom elements natively. Add cs- to your compilerOptions.isCustomElement config to suppress unknown element warnings:

// vite.config.js
vue({ template: { compilerOptions: { isCustomElement: tag => tag.startsWith('cs-') } } })

Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import '@cumulus-ui/components';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- component.html -->
<cs-button variant="primary" (click)="handleClick()">Save</cs-button>

Theming

Dark Mode

document.body.classList.add('awsui-dark-mode');

Compact Density

document.body.classList.add('awsui-compact-mode');

Both classes can be combined. They toggle Cloudscape design tokens at the CSS custom property level, so all components respond automatically.

Scripts

| Script | Command | Description | |--------|---------|-------------| | Dev server | npm run dev | Start Vite dev server on port 3000 | | Build | npm run build | Clean + ESM bundle + type declarations | | Build CDN | npm run build:cdn | Self-contained minified ESM bundle | | Build demo | npm run build:demo | Build demo pages for deployment | | Test | npm test | Build CDN bundle, then run Playwright tests | | Typecheck | npm run typecheck | TypeScript type checking (no emit) | | Generate styles | npm run generate:styles | Extract and transform Cloudscape CSS into Lit styles | | Generate interfaces | npm run generate:interfaces | Extract Cloudscape TypeScript interfaces | | Capture baselines | npm run capture:baselines | Capture Cloudscape visual baselines for comparison |

Architecture

src/
  {component}/
    interfaces.ts   # Auto-generated TypeScript interfaces (DO NOT EDIT)
    styles.ts        # Auto-generated Lit CSS from Cloudscape (DO NOT EDIT)
    internal.ts      # Lit element implementation
    index.ts         # Public export + customElements.define()
  internal/
    base-element.ts  # CsBaseElement — shared base class
    mixins/          # FormAssociatedMixin, etc.
    events.ts        # fireNonCancelableEvent helper
    styles/          # Shared and internal component styles
    generated/       # Auto-generated shared types
  index.ts           # Barrel export for all components

Dependencies

| Package | Purpose | |---------|---------| | Lit 3 | Reactive web component base | | @lit/context | Context protocol for FormField | | @floating-ui/dom | Popover/tooltip positioning | | @cumulus-ui/design-tokens | Cloudscape design token values |

References

• Cloudscape Design System — AWS's open-source design system
• Cumulus UI Documentation
• Rainforest — Kevin Hoyt's Cloudscape-inspired web components

License

Apache-2.0

This project includes derived works from Cloudscape Design Components (Apache-2.0) and bundles Lit (BSD-3-Clause) and Floating UI (MIT) in CDN builds. See NOTICE for details.