<commit_before>---
layout: spec
title: Signals
permalink: /docs/signals/index.html
---

**Signals** are dynamic variables that parameterize a visualization and can drive interactive behaviors. Signals can be used throughout a Vega specification, for example to define a mark property or data transform parameter.

Signal values are _reactive_: they can update in response to input event streams, external API calls, or changes to upstream signals. [Event streams](../event-streams) capture and sequence input events, such as `mousedown` or `touchmove`. When an event occurs, signals with associated event handlers are re-evaluated in their specification order. Updated signal values then propagate to the rest of the specification, and the visualization is re-rendered automatically.

A signal definition, and its use in the rest of a specification, looks something like this:


{: .suppress-error}
```json
{
  "signals": [
    {
      "name": "indexDate",
      "description": "A date value that updates in response to mousemove.",
      "update": "datetime(2005, 0, 1)",
      "on": [{"events": "mousemove", "update": "invert('xscale', x())"}]
    }
  ],
  "data": [
    { "name": "stocks", ... },
    {
      "name": "index",
      "source": "stocks",
      "transform": [
        {
          "type": "filter",
          "expr": "month(datum.date) === month(indexDate)"
        }
      ]
    }
  ],
  "scales": [
    { "name": "x", "type": "time", ... }
  ],
  "marks": [
    {
      "type": "rule",
      "encode": {
        "update": {
          "x": {"scale": "x", "signal": "indexDate"}
        }
      }
    }
  ]
}
```

## Signal Properties

Signal definitions may use the following properties.

| Property            | Type                | Description  |
| :------------------ | :-----------------: | :------------|
| name                | {% include type t="String" %}  | {% include required %} A unique name for the signal. Signal names should be valid [JavaScript identifiers](https://developer.mozilla.org/en-US/docs/Glossary/Identifier): they should contain only alphanumeric characters (or "$", or "_") and may not start with a digit. Reserved keywords that may **not** be used as signal names are `"datum"`, `"event"`, `"item"`, and `"parent"`.|
| bind                | [Bind](#bind)                  | Binds the signal to an external input element such as a slider, selection list or radio button group.|
| description         | {% include type t="String" %}  | A text description of the signal, useful for inline documentation.|
| on                  | {% include array t="[Handler](#handlers)" %} | An array of [event stream handlers](#handlers) for updating the signal value in response to input events.|
| init                | [Expression](../expressions)   | {% include tag ver="4.4" %} An initialization expression for the value of the signal. This expression will be invoked once and only once. The _init_ and _update_ parameters are mutually exclusice and can not be used together.|
| update              | [Expression](../expressions)   | An update expression for the value of the signal. This expression may include other signals, in which case the signal will automatically update in response to upstream signal changes, so long as the _react_ property is not `false`. The _init_ and _update_ parameters are mutually exclusive and can not be used together.|
| react               | {% include type t="Boolean" %} | A boolean flag (default `true`) indicating if the _update_ expression should be automatically re-evaluated when any upstream signal dependencies update. If `false`, the update expression will not register any dependencies on other signals, even for initialization.|
| value               | {% include type t="Any" %}     | The initial value of the signal (default `undefined`). This value is assigned prior to evaluating either the _init_ or _update_ expression.|

### Built-in signals

A few signal names are automatically processed and/or reserved:

- Signals for the [specification](../specification) `width`, `height`, `padding`, and `autosize` properties are automatically defined. Specifications may include definitions for these signals: the _value_ property will be ignored, but the _update_ and _on_ properties may be used to dynamically update these view settings.
- Group mark instances automatically include a `parent` signal bound to the data object for that group. Specifications may **not** define a signal named `parent`.
- The signal names `datum`, `item`, and `event` are reserved for top-level variables within expressions. Specifications may **not** define signals named `datum`, `item` or `event`.
- If you define a signal named `cursor`, its value will automatically drive the [CSS mouse cursor](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor) for the Vega view. For more, see the [`cursor` signal documentation](#cursor) below.

### <a name="cursor"></a>The `cursor` Signal

By default, Vega will style the mouse pointer when it is over a mark with a defined `cursor` property. However, in some interactive use cases, the cursor style should persist for the entire duration of an interaction (e.g., while dragging, regardless if the cursor remains over the item where the drag initiated). For more control, Vega provides a dedicated `cursor` signal. When the value of this signal is set, Vega uses it in lieu of any cursor properties set on marks. If the value is set to `"default"`, Vega resumes using the mark-based `cursor` property.

### Nested Signals

Signals can be defined either in the top-level scope of a specification or within a group mark definition. If a signal is defined within a nested group, it is accessible _only_ within the scope of that group; any marks, axes, legends, _etc._ that reference the signal must be contained within the group. If a nested signal has the same name as a signal defined in an outer scope, the new signal will _override_ the previously defined signal.

In addition to new signal definitions, nested group marks may contain _signal updates_ that target a signal defined in an outer scope. The `"push": "outer"` property indicates that, rather than create a new signal, updates should explicitly target an existing signal. Nested signal updates may **not** include _value_ or _update_ properties. The supported properties for signal updates are:

| Property            | Type                           | Description  |
| :------------------ | :----------------------------: | :------------|
| name                | {% include type t="String" %}  | {% include required %} The name of the signal to update.|
| push                | {% include type t="String" %}  | {% include required %} To indicate an update to a signal defined in an outer scope, the _push_ property must be set to `"outer"`.|
| description         | {% include type t="String" %}  | A text description of the signal, useful for documentation.|
| on                  | {% include array t="[Handler](#handlers)" %} | An array of [event stream handlers](#handlers) for updating the signal value in response to input events.|
<commit_msg>Fix typo in signals documentation.<commit_after>---
layout: spec
title: Signals
permalink: /docs/signals/index.html
---

**Signals** are dynamic variables that parameterize a visualization and can drive interactive behaviors. Signals can be used throughout a Vega specification, for example to define a mark property or data transform parameter.

Signal values are _reactive_: they can update in response to input event streams, external API calls, or changes to upstream signals. [Event streams](../event-streams) capture and sequence input events, such as `mousedown` or `touchmove`. When an event occurs, signals with associated event handlers are re-evaluated in their specification order. Updated signal values then propagate to the rest of the specification, and the visualization is re-rendered automatically.

A signal definition, and its use in the rest of a specification, looks something like this:


{: .suppress-error}
```json
{
  "signals": [
    {
      "name": "indexDate",
      "description": "A date value that updates in response to mousemove.",
      "update": "datetime(2005, 0, 1)",
      "on": [{"events": "mousemove", "update": "invert('xscale', x())"}]
    }
  ],
  "data": [
    { "name": "stocks", ... },
    {
      "name": "index",
      "source": "stocks",
      "transform": [
        {
          "type": "filter",
          "expr": "month(datum.date) === month(indexDate)"
        }
      ]
    }
  ],
  "scales": [
    { "name": "x", "type": "time", ... }
  ],
  "marks": [
    {
      "type": "rule",
      "encode": {
        "update": {
          "x": {"scale": "x", "signal": "indexDate"}
        }
      }
    }
  ]
}
```

## Signal Properties

Signal definitions may use the following properties.

| Property            | Type                | Description  |
| :------------------ | :-----------------: | :------------|
| name                | {% include type t="String" %}  | {% include required %} A unique name for the signal. Signal names should be valid [JavaScript identifiers](https://developer.mozilla.org/en-US/docs/Glossary/Identifier): they should contain only alphanumeric characters (or "$", or "_") and may not start with a digit. Reserved keywords that may **not** be used as signal names are `"datum"`, `"event"`, `"item"`, and `"parent"`.|
| bind                | [Bind](#bind)                  | Binds the signal to an external input element such as a slider, selection list or radio button group.|
| description         | {% include type t="String" %}  | A text description of the signal, useful for inline documentation.|
| on                  | {% include array t="[Handler](#handlers)" %} | An array of [event stream handlers](#handlers) for updating the signal value in response to input events.|
| init                | [Expression](../expressions)   | {% include tag ver="4.4" %} An initialization expression for the value of the signal. This expression will be invoked once and only once. The _init_ and _update_ parameters are mutually exclusive and can not be used together.|
| update              | [Expression](../expressions)   | An update expression for the value of the signal. This expression may include other signals, in which case the signal will automatically update in response to upstream signal changes, so long as the _react_ property is not `false`. The _init_ and _update_ parameters are mutually exclusive and can not be used together.|
| react               | {% include type t="Boolean" %} | A boolean flag (default `true`) indicating if the _update_ expression should be automatically re-evaluated when any upstream signal dependencies update. If `false`, the update expression will not register any dependencies on other signals, even for initialization.|
| value               | {% include type t="Any" %}     | The initial value of the signal (default `undefined`). This value is assigned prior to evaluating either the _init_ or _update_ expression.|

### Built-in signals

A few signal names are automatically processed and/or reserved:

- Signals for the [specification](../specification) `width`, `height`, `padding`, and `autosize` properties are automatically defined. Specifications may include definitions for these signals: the _value_ property will be ignored, but the _update_ and _on_ properties may be used to dynamically update these view settings.
- Group mark instances automatically include a `parent` signal bound to the data object for that group. Specifications may **not** define a signal named `parent`.
- The signal names `datum`, `item`, and `event` are reserved for top-level variables within expressions. Specifications may **not** define signals named `datum`, `item` or `event`.
- If you define a signal named `cursor`, its value will automatically drive the [CSS mouse cursor](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor) for the Vega view. For more, see the [`cursor` signal documentation](#cursor) below.

### <a name="cursor"></a>The `cursor` Signal

By default, Vega will style the mouse pointer when it is over a mark with a defined `cursor` property. However, in some interactive use cases, the cursor style should persist for the entire duration of an interaction (e.g., while dragging, regardless if the cursor remains over the item where the drag initiated). For more control, Vega provides a dedicated `cursor` signal. When the value of this signal is set, Vega uses it in lieu of any cursor properties set on marks. If the value is set to `"default"`, Vega resumes using the mark-based `cursor` property.

### Nested Signals

Signals can be defined either in the top-level scope of a specification or within a group mark definition. If a signal is defined within a nested group, it is accessible _only_ within the scope of that group; any marks, axes, legends, _etc._ that reference the signal must be contained within the group. If a nested signal has the same name as a signal defined in an outer scope, the new signal will _override_ the previously defined signal.

In addition to new signal definitions, nested group marks may contain _signal updates_ that target a signal defined in an outer scope. The `"push": "outer"` property indicates that, rather than create a new signal, updates should explicitly target an existing signal. Nested signal updates may **not** include _value_ or _update_ properties. The supported properties for signal updates are:

| Property            | Type                           | Description  |
| :------------------ | :----------------------------: | :------------|
| name                | {% include type t="String" %}  | {% include required %} The name of the signal to update.|
| push                | {% include type t="String" %}  | {% include required %} To indicate an update to a signal defined in an outer scope, the _push_ property must be set to `"outer"`.|
| description         | {% include type t="String" %}  | A text description of the signal, useful for documentation.|
| on                  | {% include array t="[Handler](#handlers)" %} | An array of [event stream handlers](#handlers) for updating the signal value in response to input events.|

{'fraction_non_alphanumeric': 0.11174945701674491, 'fraction_numerical': 0.0011209976879422686, 'mean_word_length': 3.230586840545347, 'pattern_counts': {'":': 50, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3996295', 'n_tokens_mistral': 3607, 'n_tokens_neox': 3404, 'n_words': 1772}