Component API

Attributes / Properties

All attributes are reflected as camelCase properties on the element.

Attribute	Property	Type	Required	Default	Description
`base-url`	`baseUrl`	`string`	Yes	—	Canary API base URL (e.g. `https://rest.eus.canaryspeech.com`)
`access-token`	`accessToken`	`string`	Yes	—	Bearer token for Canary API
`project-id`	`projectId`	`string`	Yes *	—	Canary project UUID. Required unless `project-code` is set.
`project-code`	`projectCode`	`string`	Yes *	—	Human-readable project code (e.g. `WELL3`). Alternative to `project-id`.
`subject-id`	`subjectId`	`string`	Yes *	—	Patient / user UUID. Required unless `subject-name` is set.
`subject-name`	`subjectName`	`string`	Yes *	—	Human-readable subject username. Alternative to `subject-id`.
`survey-code`	`surveyCode`	`string`	No	`""`	Selects a specific survey by code. If omitted, the first available survey is used.
`lang`	`lang`	`"en" \| "es"`	No	`"en"`	UI language
`show-results`	`showResults`	`boolean`	No	`true`	Whether to display score visualization after submission

* Either project-id or project-code must be provided (not both). Either subject-id or subject-name must be provided (not both).

Setting properties imperatively:

const el = document.querySelector("cs-voice-survey");
el.accessToken = "new-token";
el.projectCode = "WELL3";
el.subjectName = "john.doe";

Custom Events

All events bubble (bubbles: true) and cross Shadow DOM boundaries (composed: true).

Event	`detail` shape	Fired when
`survey-loaded`	`{ surveyCode, surveyVersion, surveyName }`	Survey definition fetched successfully
`recording-started`	`{ assessmentId }`	User tapped record and `beginAssessment` succeeded
`recording-stopped`	`{ duration }`	User stopped recording (seconds)
`submitted`	`{ assessmentId }`	Audio upload has begun
`completed`	`{ assessmentId, scores }`	Assessment is fully complete
`survey-error`	`{ status, message }`	Any error in the flow

document.querySelector("cs-voice-survey").addEventListener("completed", (e) => {
  console.log("Assessment ID:", e.detail.assessmentId);
  console.log("Scores:", e.detail.scores);
});

CSS Custom Properties (Theming)

Override these on the cs-voice-survey element (or any ancestor) to customize appearance.

cs-voice-survey {
  --vs-color-primary: #008cff;
  --vs-color-accent: #10b981;
  --vs-color-purple: #2f215b;
  --vs-color-purple-mid: #675797;
  --vs-color-purple-light: #8d81b1;
  --vs-color-bg: #ffffff;
  --vs-font-family: system-ui, sans-serif;
  --vs-border-radius: 12px;
  --vs-record-btn-size: 88px;
}

See the Theming page for full details and examples.

CSS Parts

Use ::part() to style internal structural elements.

Part name	Element
`::part(card)`	The survey prompt card container
`::part(record-button)`	The circular microphone / stop button
`::part(completion)`	The results section on the completion screen
`::part(score-track)`	The gradient range track in score visualizations

cs-voice-survey::part(card) {
  border: 2px solid #e0d4f7;
  box-shadow: 0 4px 24px rgba(47, 33, 91, 0.12);
}

Exported JavaScript API

import {
  VoiceSurvey,
  AssessmentController,
  type CanaryConfig,
  type ScoreItem,
  type SurveyDefinition,
  type AssessmentStatus,
} from "cs-voice-survey-component";