Web Component Integration

Learn how to use Sibilance as a web component for framework-agnostic integration.

Overview

Sibilance provides pre-built web components that work in any framework or vanilla JavaScript:

<sibilance-survey-widget> - Complete voice survey widget
<sibilance-microphone> - Standalone microphone button

Installation

bash

npm install @sibilance.is/client

Or use via CDN:

html

<script type="module" src="https://unpkg.com/@sibilance.is/client/dist/web-components.js"></script>

Quick Start

Register Components

typescript

import { registerSibilanceWebComponents } from '@sibilance.is/client';

// Register all web components
registerSibilanceWebComponents();

Use in HTML

html

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <h1>Welcome</h1>
  
  <!-- Sibilance Survey Widget -->
  <sibilance-survey-widget 
    survey-key="sibilance_your_key_here"
    position="bottom-right">
  </sibilance-survey-widget>

  <script type="module">
    import { registerSibilanceWebComponents } from '@sibilance.is/client';
    
    // Register components
    registerSibilanceWebComponents();
  </script>
</body>
</html>

Web Components

`<sibilance-microphone>`

Floating microphone button for voice survey interaction.

html

<sibilance-microphone
  survey-key="sibilance_your_key_here"
  position="bottom-right"
  size="medium"
  auto-start="false">
</sibilance-microphone>

Attributes:

survey-key - Your Survey Key (required)
position - bottom-right | bottom-left | top-right | top-left (default: bottom-right)
size - small | medium | large (default: medium)
auto-start - Auto-start session on load (default: false)

JavaScript API:

javascript

const mic = document.querySelector('sibilance-microphone');

// Start session
await mic.startSession();

// Stop session
await mic.stopSession();

// Check state
console.log(mic.isConnected);
console.log(mic.isListening);

`<sibilance-survey-widget>`

Complete survey widget with microphone and status display.

html

<sibilance-survey-widget
  survey-key="sibilance_your_key_here"
  position="bottom-right"
  show-status="true">
</sibilance-survey-widget>

Attributes:

survey-key - Your Survey Key (required)
position - bottom-right | bottom-left | top-right | top-left (default: bottom-right)
show-status - Show survey status display (default: true)

Framework Integration

Vanilla JavaScript

html

<!DOCTYPE html>
<html>
<head>
  <title>Sibilance Demo</title>
</head>
<body>
  <h1>My Website</h1>
  
  <sibilance-microphone 
    survey-key="sibilance_your_key_here"
    position="bottom-right">
  </sibilance-microphone>

  <script type="module">
    import { registerSibilanceWebComponents } from '@sibilance.is/client';
    
    // Register components
    registerSibilanceWebComponents();
    
    // Listen for events
    const mic = document.querySelector('sibilance-microphone');
    
    mic.addEventListener('survey-complete', (event) => {
      console.log('Survey completed!', event.detail);
      // event.detail contains the YAML results
    });
    
    mic.addEventListener('survey-error', (event) => {
      console.error('Survey error:', event.detail);
    });
  </script>
</body>
</html>

React

tsx

import { useEffect } from 'react';
import { registerSibilanceWebComponents } from '@sibilance.is/client';

// Register once
registerSibilanceWebComponents();

function App() {
  useEffect(() => {
    const mic = document.querySelector('sibilance-microphone');
    
    mic?.addEventListener('survey-complete', (event: any) => {
      console.log('Survey completed!', event.detail);
    });
  }, []);

  return (
    <div>
      <h1>My App</h1>
      {/* Use web component in React */}
      <sibilance-microphone 
        survey-key={process.env.NEXT_PUBLIC_SIBILANCE_SURVEY_KEY}
        position="bottom-right" 
      />
    </div>
  );
}

Vue

vue

<script setup lang="ts">
import { onMounted } from 'vue';
import { registerSibilanceWebComponents } from '@sibilance.is/client';

onMounted(() => {
  registerSibilanceWebComponents();
  
  const mic = document.querySelector('sibilance-microphone');
  mic?.addEventListener('survey-complete', (event: any) => {
    console.log('Survey completed!', event.detail);
  });
});
</script>

<template>
  <div>
    <h1>My App</h1>
    <!-- Use web component in Vue -->
    <sibilance-microphone 
      survey-key="sibilance_your_key_here"
      position="bottom-right" 
    />
  </div>
</template>

Angular

typescript

// app.component.ts
import { Component, OnInit, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { registerSibilanceWebComponents } from '@sibilance.is/client';

@Component({
  selector: 'app-root',
  template: `
    <h1>My App</h1>
    <sibilance-microphone 
      survey-key="sibilance_your_key_here"
      position="bottom-right">
    </sibilance-microphone>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppComponent implements OnInit {
  ngOnInit() {
    registerSibilanceWebComponents();
    
    const mic = document.querySelector('sibilance-microphone');
    mic?.addEventListener('survey-complete', (event: any) => {
      console.log('Survey completed!', event.detail);
    });
  }
}

Svelte

svelte

<script>
  import { onMount } from 'svelte';
  import { registerSibilanceWebComponents } from '@sibilance.is/client';
  
  onMount(() => {
    registerSibilanceWebComponents();
    
    const mic = document.querySelector('sibilance-microphone');
    mic?.addEventListener('survey-complete', (event) => {
      console.log('Survey completed!', event.detail);
    });
  });
</script>

<h1>My App</h1>
<sibilance-microphone 
  survey-key="sibilance_your_key_here"
  position="bottom-right" 
/>

Events

Listen to custom events:

javascript

const mic = document.querySelector('sibilance-microphone');

// Survey completed
mic.addEventListener('survey-complete', (event) => {
  console.log('Survey completed!', event.detail);
  // event.detail contains YAML results array
});

// Survey error
mic.addEventListener('survey-error', (event) => {
  console.error('Error:', event.detail);
});

// Session started
mic.addEventListener('session-started', () => {
  console.log('Session started');
});

// Session stopped
mic.addEventListener('session-stopped', () => {
  console.log('Session stopped');
});

// State changed
mic.addEventListener('state-changed', (event) => {
  console.log('State:', event.detail);
});

Styling

CSS Custom Properties

css

sibilance-microphone {
  --sibilance-primary-color: #007bff;
  --sibilance-background: #ffffff;
  --sibilance-border-radius: 50%;
  --sibilance-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

sibilance-survey-widget {
  --widget-background: #f8f9fa;
  --widget-text-color: #212529;
  --widget-border-color: #dee2e6;
}

Custom Styling

css

/* Override default styles */
sibilance-microphone::part(button) {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border: none;
  box-shadow: 0 8px 16px rgba(102, 126, 234, 0.4);
}

sibilance-microphone::part(button):hover {
  transform: scale(1.1);
}

TypeScript Support

typescript

import type { SibilanceMicrophoneElement } from '@sibilance.is/client';

const mic = document.querySelector('sibilance-microphone') as SibilanceMicrophoneElement;

// Typed properties and methods
await mic.startSession();
console.log(mic.isConnected);

Best Practices

Register Once - Register web components once at app initialization
Custom Elements - Enable custom elements schema in your framework
Event Listeners - Use event listeners for state changes
Styling - Use CSS custom properties for theming
Cleanup - Remove event listeners when components unmount
TypeScript - Use type definitions for better DX

Browser Support

Web components require:

Chrome/Edge 67+
Firefox 63+
Safari 10.1+

For older browsers, use a polyfill:

html

<script src="https://unpkg.com/@webcomponents/webcomponentsjs@2/webcomponents-loader.js"></script>

Standalone JS - Vanilla JavaScript integration
React - React integration
Sibilance Client - Core client API
API Reference - Complete API documentation

Web Component Integration ​

Overview ​

Installation ​

Quick Start ​

Register Components ​

Use in HTML ​

Web Components ​

<sibilance-microphone> ​

<sibilance-survey-widget> ​

Framework Integration ​

Vanilla JavaScript ​

React ​

Vue ​

Angular ​

Svelte ​

Events ​

Styling ​

CSS Custom Properties ​

Custom Styling ​

TypeScript Support ​

Best Practices ​

Browser Support ​

Related ​

Web Component Integration

Overview

Installation

Quick Start

Register Components

Use in HTML

Web Components

`<sibilance-microphone>`

`<sibilance-survey-widget>`

Framework Integration

Vanilla JavaScript

React

Vue

Angular

Svelte

Events

Styling

CSS Custom Properties

Custom Styling

TypeScript Support

Best Practices

Browser Support

Related