[Traits](https://oods-foundry.com/traits) / InteractionHighlight

# InteractionHighlight

Emphasizes hovered or selected points by adjusting a configurable visual property.

Generated from @oods/foundry 0.10.1

- Group

  viz.interaction

- Maturity

  alpha

- Contexts

  none listed

## 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)
```