---
url: /mosaic/api/vgplot/plot.md
---

# Plot {#plot-page}

A `Plot` is defined using a set of directives that specify [*attributes*](./attributes), graphical [*marks*](./marks), [*interactors*](./interactors), and [*legends*](./legends).

**(begin JavaScript API)**

```js
plot(
  width(500), // attribute
  rectY(from("table"), { x1: "u", x2: "v", y: "w", fill: "c" }), // mark
  intervalX({ as: selection }), // interactor
  colorLegend() // legend
)
```

**(end JavaScript API)**

**(begin Python API)**

```python
import vgplot as vg

vg.plot(
    vg.width(500),  # attribute
    vg.rect_y(vg.source("table"), x1="u", x2="v", y="w", fill="c"),  # mark
    vg.interval_x(bind=selection),  # interactor
    vg.color_legend(),  # legend
)
```

**(end Python API)**

## plot

**(begin JavaScript API)**

`plot(...directives)`

Create a new `Plot` instance based on the provided *directives* and return the corresponding HTML element.

**(end JavaScript API)**

**(begin Python API)**

`vg.plot(...directives)`

Build a plot specification from the provided *directives* for use with Mosaic widgets or other consumers.

**(end Python API)**

## Plot {#plot-class}

**(begin JavaScript API)**

`new Plot(element)`

Class definition for a `Plot`.
If provided, the input *element* will be used as the container for the plot, otherwise a new `div` element will be generated.

### element

`plot.element`

The HTML element containing the plot.

### margins

`plot.margins()`

Return the specified margins of the plot as an object of the form `{left, right, top, bottom}`.

### innerWidth

`plot.innerWidth()`

Return the "inner" width of the plot, which is the `width` attribute value minus the `leftMargin` and `rightMargin` values.

### innerHeight

`plot.innerHeight()`

Return the "inner" height of the plot, which is the `height` attribute value minus the `topMargin` and `bottomMargin` values.

### pending

`plot.pending(mark)`

Called by a [`Mark`](./marks) instance to inform this parent plot that the mark has a pending data update.

### update

`plot.update(mark)`

Called by a [`Mark`](./marks) instance to inform this parent plot that the mark has completed an update.

### render

`plot.render()`

Renders this plot within its container element.

### getAttribute

`plot.getAttribute(name)`

Returns the attribute value for the given attribute *name*.
Called by [attribute directives](./attributes.md).

### setAttribute

`plot.setAttribute(name, value, options)`

Sets the attribute value for the given attribute *name*.
Returns `true` if the attribute is updated to a new value, `false` otherwise.
The *options* hash may include a *silent* flag to suppress listener updates.
Called by [attribute directives](./attributes.md).

### addAttributeListener

`plot.addAttributeListener(name, callback)`

Adds an event listener *callback* that is invoked when the attribute with the given *name* is updated.

### removeAttributeListener

`plot.removeAttributeListener(name, callback)`

Removes an event listener *callback* associated with the given attribute *name*.

### addParams

`plot.addParams(mark, paramSet)`

Register a set of [Params](../core/param) associated with a *mark* to coordinate updates.
Called by child [`Mark`](./marks) instances.

### addMark

`plot.addMark(mark)`

Add a [`Mark`](./marks) instance to this plot.
Called by [mark directives](./marks).

### markSet

`plot.markSet`

Property getter that returns a [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) containing this plot's marks.

### addInteractor

`plot.addInteractor(interactor)`

Add an interactor to this plot.
Called by [interactor directives](./interactors).

### addLegend

`plot.addLegend(legend, include)`

Add a *legend* associated with this plot.
The *include* flag (default `true`) indicates if the legend should be included within the same container element as the plot.
Called by [legend directives](./legends).


**(end JavaScript API)**

**(begin Python API)**

The `Plot` class is a JavaScript runtime concept for embedding plots in the browser. In Python, [`vg.plot(...)`](#plot) returns a serializable specification rather than a live plot object, so there is no `Plot` class or instance methods.

**(end Python API)**