> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Plugin development API

> Reference the Sigma Plugin API arguments, events, and methods for building custom workbook plugin elements.

## The PluginConfigOptions Object

Arguments

**name** string

An identifier and label for the individual configuration option.

**type** string

The configuration option’s input type:

* **element**: Allows users to reference a data element in the workbook. Typically used for data source selection.
* **column**: Allows users to select data element columns. *PluginConfigOptions* assigned this type must also include source and allowMultiple arguments.
* **text**: Allows users to input text into a text box. *PluginConfigOptions* assigned this type must also include secure, multiline, placeholder, and default value arguments.
* **group**: Allows users to group multiple *PluginConfigOptions*. This configuration type can only contain “text” *type* objects.
* **toggle**: Allows users to choose between two boolean values.
* **checkbox**: Allows users to select options.

**source** string (ignored if *type* does not equal “column”)

The *name* argument of the PluginConfigOptions object (*type* “element”) that stores the data element to be used as a data source.

**allowMultiple** boolean (ignored if *type* does not equal “column”)

True allows users to select multiple values.

**allowTypes** string | undefined (ignored if *type* does not equal “column”)

A list if any or all column types you want to prevent users from inputting.

Options: 'boolean', 'datetime', 'number', 'integer', 'text', 'variant', 'link', 'error'

**secure** boolean | undefined (ignored if *type* does not equal “text”)

If true:

* A password input type is applied to the text box
* The input value is not passed as plaintext through the query string (for pre-hydrated configs). The value is only made available once a secure connection between the plugin and workbook has been established.

If false:

* Default text input is used.
* The input value is passed as plaintext through the query string, allowing the value to be accessed immediately in the plugin.

**Multiline** boolean | undefined (ignored if *type* does not equal “text”)

Uses `<textarea />` instead of `<input />`.

***Note***: Can still be set as secure but will no longer use the password type.

**placeholder** string | undefined (ignored if *type* does not equal “text”)

Placeholder text for the text input.

**defaultValue** string | undefined (ignored if *type* does not equal “text”)

A value to use as the default in a text input if no value is set.

### Examples

Example #1

The object below displays a select menu. The menu includes all data elements in the workbook. Users will select an element from this list to be used as the data source for their plugin-based element.

`{ name: 'data source', type: 'element' }`

Example #2

The object below displays a select menu. The menu that lists every column in the data element the user selected as a data source in the “data source” input (see Example #1 above). Because allowMultiple is **true**, the user can select multiple columns from the list.

`{ name: 'dimension', type: 'column', source: 'data source', allowMultiple: **true** }`

## Configuration API

client.config.configureEditorPanel(editorPanelConfiguration)

Configures the workbook’s editor panel for the plugin.

Arguments

**editorPanelConfiguration** array\<\{PluginConfigOptions}>

A list of *PluginConfigOptions* objects that define the inputs available in the plugin element’s editor panel.

Example

```javascript
client.config.configureEditorPanel([
  { name: 'data source', type: 'element' },
  { 
    name: 'dimension',
    type: 'column',
    source: 'data source',
    allowMultiple: true
  },
  { name: 'measures', type: 'column', source: 'data source', allowMultiple: true },
  { name: 'a group of values', type: 'group' },
  { name: 'text input #1', source: 'a group of values', type: 'text' },
  { name: 'text input #2', source: 'a group of values', type: 'text' },
  { name: 'apiKey', type: 'text', secure: true },
]);
```

### client.config.get()

Returns the array of *PluginConfigOptions*.

Arguments

*none*

### client.config.getKey(key)

Returns a specific *PluginConfigOptions* object based on the input string.

Arguments

**key** string

The *name* of the target *PluginConfigOptions* object

### client.config.set(config)

Updates the plugin configuration for one or more key/value pairs and saves it to the workbook.

Arguments

**config** array\<\{key: string, value: string}>

The key / value pair to save, where **key** is the *name* of the *PluginConfigOptions* object and **value** is the user’s input value.

### client.config.setKey(key, value)

Updates the input value associated with a specific *PluginConfigOptions* object and saves it to the workbook.

***Note***: To set multiple values at once, use client.config.set(config).

Arguments

**key** string

The *name* of the associated *PluginConfigOptions* object

**value** any

The user’s input value.

### client.config.subscribe(listener)

Subscribes to configuration changes.

Arguments

**listener** config => void

A function to be invoked when changes are made to the configuration.

## Standard Javascript API

client.config.getElementColumns(elementId)

Returns a Promise that resolves to the column information from the specified element.

Arguments

**elementId** string

A workbook element’s unique identifier.

### client.elements.subscribeToElementColumns(elementId, listener)

Subscribes to changes in a specific element’s column information.

Arguments

**elementId** string

A workbook element’s unique identifier.

**listener** function

A callback function to be invoked

### client.elements.subscribeToElementData(elementId, listener)

Subscribes to changes in a specific element’s data rows. The shape of the data is a dictionary of cell data keyed by its columnId: Dictionary\&lt;ColumnId, CellValue\[]>.

Arguments

**elementId** string

A workbook element’s unique identifier.

**listener** function

A callback function to be invoked

## Hooks API

The Hooks API, built using React Hooks, is included in the Sigma plugin client package.

### useElementColumns(elementId)

Returns the column information from the specified element.

Arguments

**elementId** string

A workbook element’s unique identifier.

### useElementData(elementId)

Returns the row data from the specified element. The shape of the data is a dictionary of cell data keyed by its columnId: Dictionary\&lt;ColumnId, CellValue\[]>.

Arguments

**elementId** string

A workbook element’s unique identifier.

### useConfig(key)

Returns the workbook element’s current configuration. If a key is provided, only the associated configuration is returned.

Arguments

**key** string \[optional]

The *name* of the associated *PluginConfigOptions* object.

## Related resources

* [Get started with custom plugins](/docs/get-started-with-custom-plugins)
* [Develop plugins for Sigma](/docs/develop-plugins-for-sigma)