Settings Api

api.settings

Get/Set

Getting or setting any value on the settings api will get/set the value of the setting with the corresponding id, if it exists.

Methods

listen()

listen(key, callback): () => void

Fires a callback whenever a setting changes

Parameters

Parameter	Type
key	string
callback	(value, remote) => void

Returns

Function

A function to stop listening

---

create()

create(description): void

Initializes the settings menu for the script

Parameters

Parameter	Type
description	(PluginSetting | SettingGroup)[]

Settings

All settings (aside from “custom”, “group”, and “transclude”) inherit these properties.

Property	Type	Description
id	string	The key which can be used to access the value of setting
title	string	The title of the setting in the settings menu
description?	string	A description for the setting in the settings menu
default?	T	The default value of the setting
onChange?	(value, remote) => void	A callback that fires when the setting changes

Setting	Type	Options	Notes
dropdown	string	options: { label: string; value: string }[] allowNone?: boolean
multiselect	string[]	options: { label: string; value: string }[]
number	number	min?: number max?: number step?: number
toggle	boolean
text	string	placeholder?: string maxLength?: number
slider	number	min: number max: number step?: number ticks?: number[] formatter?: (value: number) => string	Ticks are placed at the start and end by default
radio	string	options: { label: string; value: string }[]
color	string	rgba?: boolean	When rgba is true, the value takes the form rgba(100,120,140,0.5). Otherwise it is a hex code.
custom	any	render: SettingRenderer
customsection	any	render: SettingRenderer	Custom sections do not have a built-in title or description.
group	N/A	id?: string title: string description?: string settings: PluginSetting[]
togglegroup	boolean	settings: PluginSetting[]
transclude	N/A	fromPlugin: string id: string label?: string hideIfMissing?: boolean

The “custom” and “customsection” settings require a render function, which looks like so: (container: HTMLElement, currentValue: any, update: (newValue: any) => void) => (() => void) | void. The function can return a callback to be run when the element is unmounted.

The “transclude” setting shows a setting from the plugin specified by fromPlugin with the id given. This can include groups/togglegroups but not other transclude settings. Changing the transcluded setting will trigger the relevant listeners in the plugin it is coming from.

Returns

A reference to api.settings, with inferred types if @gimloader/types is installed

Settings