InteractionHighlight · Traits

Fields it adds

Field	Type	Required	Description
`viz_interaction_highlight_fields`	`string[]`	yes	Fields copied into the interaction predicate.
`viz_interaction_highlight_trigger`	`string` (hover, click, focus)	yes	Event stream used for highlight activation.
`viz_interaction_highlight_property`	`string`	yes	Visual property that is conditionally modified.
`viz_interaction_highlight_active_value`	`number`	yes	Value applied when the predicate matches.
`viz_interaction_highlight_inactive_value`	`number`	yes	Value applied when the predicate does not match.

What it shows in each context

This trait places no component of its own.

Parameters

fields string[], required: Data fields that define the highlight predicate.
trigger string: Event stream that activates the highlight.
property string: Visual property to adjust when the predicate is active.
activeValue number: Value applied to highlighted marks.
inactiveValue number: Value applied to non-highlighted marks.

States

idle, highlighted . It starts idle.

idle to highlighted, on select
highlighted to idle, on clear

Objects that use it

No shipped object uses this trait.

The trait file

traits/viz/interaction-highlight.trait.yaml

trait:
  name: InteractionHighlight
  version: 0.2.0
  description: >-
    Emphasizes hovered or selected points by adjusting a configurable visual property.
  category: viz.interaction
  tags:
    - viz
    - interaction
    - highlight

parameters:
  - name: fields
    type: string[]
    required: true
    description: Data fields that define the highlight predicate.
  - name: trigger
    type: string
    required: false
    description: Event stream that activates the highlight.
    default: hover
    validation:
      enum:
        - hover
        - click
        - focus
  - name: property
    type: string
    required: false
    description: Visual property to adjust when the predicate is active.
    default: fillOpacity
  - name: activeValue
    type: number
    required: false
    description: Value applied to highlighted marks.
    default: 1
    validation:
      minimum: 0
      maximum: 1
  - name: inactiveValue
    type: number
    required: false
    description: Value applied to non-highlighted marks.
    default: 0.35
    validation:
      minimum: 0
      maximum: 1

schema:
  viz_interaction_highlight_fields:
    type: string[]
    required: true
    description: Fields copied into the interaction predicate.
  viz_interaction_highlight_trigger:
    type: string
    required: true
    description: Event stream used for highlight activation.
    defaultFromParameter: trigger
    validation:
      enum:
        - hover
        - click
        - focus
  viz_interaction_highlight_property:
    type: string
    required: true
    description: Visual property that is conditionally modified.
    defaultFromParameter: property
  viz_interaction_highlight_active_value:
    type: number
    required: true
    description: Value applied when the predicate matches.
    defaultFromParameter: activeValue
    validation:
      minimum: 0
      maximum: 1
  viz_interaction_highlight_inactive_value:
    type: number
    required: true
    description: Value applied when the predicate does not match.
    defaultFromParameter: inactiveValue
    validation:
      minimum: 0
      maximum: 1

semantics:
  viz_interaction_highlight_fields:
    semantic_type: viz.interaction.fields
    ui_hints:
      component: ListSummary
  viz_interaction_highlight_trigger:
    semantic_type: viz.interaction.trigger
    ui_hints:
      component: Badge
  viz_interaction_highlight_property:
    semantic_type: viz.interaction.property
    ui_hints:
      component: Code
  viz_interaction_highlight_active_value:
    semantic_type: viz.interaction.value_active
    ui_hints:
      component: NumericPreview
  viz_interaction_highlight_inactive_value:
    semantic_type: viz.interaction.value_inactive
    ui_hints:
      component: NumericPreview

state_machine:
  states:
    - idle
    - highlighted
  initial: idle
  transitions:
    - from: idle
      to: highlighted
      trigger: select
    - from: highlighted
      to: idle
      trigger: clear

tokens:
  viz.interaction.highlight.active.opacity: "var(--cmp-viz-highlight-active-opacity)"
  viz.interaction.highlight.inactive.opacity: "var(--cmp-viz-highlight-inactive-opacity)"
  viz.interaction.highlight.outline: "var(--cmp-viz-highlight-outline)"

dependencies: []

metadata:
  created: "2025-11-15"
  updated: "2026-02-28"
  owners:
    - viz@oods.systems
    - accessibility@oods.systems
  maturity: alpha
  accessibility:
    keyboard: |
      Highlight is activatable via keyboard focus (trigger=focus) in addition to
      hover and click. Arrow keys navigate between data points. Enter/Space
      toggles persistent highlight on click-triggered interactions.
    screenreader: |
      When a mark is highlighted, the screen reader announces the datum values
      and indicates it is selected. Non-highlighted marks are announced as
      "dimmed" or "inactive" to convey the visual distinction.
    focusManagement: |
      Focus ring is rendered around the highlighted mark. When highlight clears,
      focus remains on the last interacted mark.
  examples:
    - ScatterplotBrushHighlight
    - BarChartCategoryHighlight
  references:
    - RDS.7 Trait-Driven Visualization System Specification (v0.1)