Components

Getting started

npm install affect-kit

Imports

Each component has its own entry point. Import only what you need:

import 'affect-kit/rater';   // registers <affect-kit-rater>
import 'affect-kit/result';  // registers <affect-kit-result>
import 'affect-kit/face';    // registers <affect-kit-face>
import 'affect-kit/compare'; // registers <affect-kit-compare>

// Or register all four at once:
import 'affect-kit';

TypeScript types

import type { Rating, EmotionLabel, EmotionName } from 'affect-kit';
import { createRating, averageRatings }           from 'affect-kit';

Quick wiring: rater → result

<affect-kit-rater id="rater"></affect-kit-rater>
<affect-kit-result id="result" show-face show-labels color-mode></affect-kit-result>

<script type="module">
  import 'affect-kit/rater';
  import 'affect-kit/result';

  const rater  = document.querySelector('affect-kit-rater');
  const result = document.querySelector('affect-kit-result');
  rater.addEventListener('change', e => result.rating = e.detail);
</script>

React

Custom elements work in React 19+ with native support, or React 18 with a thin ref wrapper. TypeScript types are available via the global HTMLElementTagNameMap augmentation shipped in each component entry point.

// React 19+
import 'affect-kit/rater';

function App() {
  return (
    <affect-kit-rater
      color-mode
      onchange={(e) => console.log(e.detail)}
    />
  );
}

2. <affect-kit-rater>

The primary capture interface. The user drags on a V/A pad to set a gut-feeling position — the face glyph and background color update in real time. On release, 55 emotion chips from the NRC VAD Lexicon rearrange by proximity to the pad position. The user taps chips to intensity-rate them at 1, 2, or 3. Every pad release and chip toggle after the first placement fires a change event with a Rating object.

Attributes / props

Events

Methods

CSS custom properties

3. <affect-kit-result>

A display panel for a captured Rating. Renders the selected emotion words scaled by intensity (level 3 is largest, level 1 is smallest), an optional face glyph, and an optional color tint. Designed to pair with <affect-kit-rater> but can also be driven from stored data. The face and color always follow rating.face (the pre-verbal pad gesture), not the composite label coordinates — preserving the visual signal of the gut feeling even when labels shift the V/A/D values.

Attributes / props

CSS custom properties

Layout custom properties

These pierce the shadow DOM and let a parent container (like <affect-kit-compare>) drive the inner face/words layout via container queries without JS:

4. <affect-kit-face>

A standalone animated face glyph driven directly by v (valence) and a (arousal) props. Runs a 60 fps animation loop by default — breath (subtle scale oscillation) and tremor (position noise scaled by arousal). Size is set via CSS; the SVG fills its container. Used internally by both <affect-kit-rater> and <affect-kit-result>.

Attributes / props

Methods

Default size

The element defaults to 120 × 120px (set via :host styles). Override freely with CSS — the SVG fills 100% of its container:

affect-kit-face { width: 80px; height: 80px; }
/* or inline: */
<affect-kit-face style="width:200px;height:200px"></affect-kit-face>

5. <affect-kit-compare>

A paired side-by-side display for two ratings or two rating arrays. When color-mode is on, the card background is a gradient from the left rating's V/A color to the right rating's V/A color — the color transition itself tells the story. Layout responds to host width via container queries: side-by-side when wide, stacked when narrow. Each half's face sits on the outer edge so the faces frame the gradient. The widget makes no claims about what the comparison means — interpretation belongs to the user.

Attributes / props

CSS custom properties

Averaging arrays

Pass a Rating[] to either side and the widget averages it automatically. Useful for windowed comparisons (e.g. last month vs last week):

import 'affect-kit/compare';
import { createRating } from 'affect-kit';

const cmp = document.querySelector('affect-kit-compare');
cmp.beforeRating = lastMonthRatings; // Rating[]
cmp.afterRating  = lastWeekRatings;  // Rating[]

6. TypeScript types

import type { Rating, EmotionLabel, EmotionName } from 'affect-kit';
import { createRating, averageRatings }           from 'affect-kit';

Rating

The central data object. Emitted by change and commit events, consumed by result and compare. Two VAD sources are preserved separately so researchers can use either or both:

interface Rating {
  /** Unix timestamp (ms) at commit time. */
  timestamp: number;

  /** Pad position that drives the face glyph and color. The pre-verbal gut gesture. */
  face: { v: number; a: number };

  /** Selected emotion words, each carrying its lexicon VAD coordinates. */
  labels: EmotionLabel[];

  /**
   * Intensity-weighted centroid of selected labels' VAD values.
   * Novel derivation grounded in affective theory — not independently validated.
   * null when no labels were selected.
   */
  composite: { v: number; a: number; d: number } | null;
}

// To get a single resolved VAD vector:
//   rating.composite ?? { v: rating.face.v, a: rating.face.a, d: 0 }

EmotionLabel

interface EmotionLabel {
  name:  EmotionName; // strict — must be in the validated vocabulary
  level: number;      // 1 | 2 | 3 from rater; widened to number for averaged data
  vad:   { v: number; a: number; d: number };
  // ^ Per-word NRC VAD Lexicon coordinates (Mohammad 2025).
  //   Pre-aggregate — direct lookup, identical for every rating that contains
  //   this name. Aggregation across labels happens only at Rating.composite.
}

createRating()

Construct a Rating from a face position and optional labels. Throws on any label name not in the validated vocabulary:

import { createRating } from 'affect-kit';

const r = createRating({
  face: { v: 0.5, a: 0.3 },  // pad position (required)
  labels: [                   // optional
    { name: 'calm',     level: 2 },
    { name: 'grateful', level: 1 },
  ],
});

averageRatings()

Average an array of Rating objects into a single Rating. Label levels are averaged continuously — the result widget renders averaged levels as continuous intermediate sizes:

import { averageRatings } from 'affect-kit';

const avg = averageRatings(sessionRatings); // Rating[] → Rating

7. React wrapper

@affect-kit/react wraps all four components using @lit/react. You get typed camelCase props, idiomatic onChange handlers, and correct property/attribute mapping — without writing any ref plumbing.

Install

npm install affect-kit @affect-kit/react

Import

import { Rater, Result, Face, Compare } from '@affect-kit/react';
import type { Rating } from 'affect-kit';

Usage

import { Rater, Result } from '@affect-kit/react';
import { useState } from 'react';
import type { Rating } from 'affect-kit';

export function RatingWidget() {
  const [rating, setRating] = useState<Rating | null>(null);

  return (
    <>
      <Rater colorMode onChange={(e) => setRating(e.detail)} />
      {rating && <Result rating={rating} showFace showLabels colorMode />}
    </>
  );
}

Props

All HTML attributes map to camelCase props (color-mode → colorMode, show-face → showFace, etc.). Complex properties (rating, beforeRating, afterRating) are passed directly as object props — no serialisation.

Events

Refs

Pass a ref to access the underlying element and call instance methods:

import { useRef } from 'react';
import { Rater } from '@affect-kit/react';
import type { AffectKitRater } from 'affect-kit/rater';

const ref = useRef<AffectKitRater>(null);
// ref.current.reset() — clears pad + chip selection