Web Components

Framework-agnostic custom elements generated from the design system. Use in any HTML page, Vue, Svelte, or any framework.

Overview

Web Components are custom HTML elements generated from the same YAML source as the CSS and React components. They use Shadow DOM for style encapsulation and <slot> elements for content projection.

Experimental

Web Components are auto-generated and currently experimental. The API may change. For production use, the CSS classes or React components are recommended.

Installation

Install bash 
npm install @deepgram/styles

Usage

Import individual web components by name. Each import registers a custom element.

Import and use html 
<!-- Import the component (registers the custom element) -->
<script type="module">
  import '@deepgram/styles/dist/components/web-components/btn.js';
  import '@deepgram/styles/dist/components/web-components/card.js';
</script>

<!-- Use the custom elements -->
<dg-btn primary>Get Started</dg-btn>

<dg-card structured>
  <h3 slot="header">Card Title</h3>
  <p>Card content goes here.</p>
</dg-card>

How It Works

Custom Element Names

Each component maps to a <dg-*> custom element. The tag name matches the component's YAML key with the dg- prefix.

Tag naming html 
<!-- YAML key: btn → <dg-btn> -->
<dg-btn>Click me</dg-btn>

<!-- YAML key: card → <dg-card> -->
<dg-card>Content</dg-card>

<!-- YAML key: action-group → <dg-action-group> -->
<dg-action-group>...</dg-action-group>

Attributes = Variants

Component variants become boolean HTML attributes, just like the React boolean props.

Variant attributes html 
<!-- Variant attributes are kebab-case -->
<dg-btn primary>Primary button</dg-btn>
<dg-btn ghost>Ghost button</dg-btn>
<dg-btn danger-ghost>Danger button</dg-btn>

<!-- Multiple variants -->
<dg-btn primary sm>Small primary</dg-btn>

<!-- Cards -->
<dg-card structured>...</dg-card>
<dg-card compact>...</dg-card>

Shadow DOM & Slots

Each component uses Shadow DOM for style isolation. Content is projected via <slot> elements. The component's CSS from the design system is embedded in the shadow root.

Slot-based content html 
<!-- The default slot receives children -->
<dg-btn primary>
  <i class="fas fa-play"></i>
  Start Recording
</dg-btn>

<!-- Named slots for structured content -->
<dg-card>
  <div slot="header">Card Header</div>
  <div slot="body">Card Body</div>
  <div slot="footer">Card Footer</div>
</dg-card>

CSS vs React vs Web Components

Choose the integration that fits your stack.

Feature CSS Classes React Web Components
Framework Any React 18+ Any
Bundle size CSS only CSS + JS CSS + JS
TypeScript — Full types —
Style isolation BEM convention BEM convention Shadow DOM
Status Stable Stable Experimental
Best for Static sites, CMS, any stack React / Next.js apps Multi-framework, micro-frontends

Generated Elements

Web components are generated for all YAML-defined components. Below is a representative selection:

Custom Element CSS Class Variant Attributes
<dg-btn> .dg-btn primary, secondary, ghost, danger-ghost, icon-only, sm, collapse
<dg-card> .dg-card structured, compact, spacious, bordered
<dg-input> .dg-input inline
<dg-alert> .dg-alert info, success, warning, error
<dg-status> .dg-status info, success, warning, error, primary, secondary
<dg-spinner> .dg-spinner —
<dg-hero> .dg-hero —
<dg-section> .dg-section compact, spacious, bordered, elevated, fieldset
<dg-code-block> .dg-code-block compact, tall, no-scroll
<dg-footer> .dg-footer —