# Inputs ## Overview When you create a [custom indicator], you can make some indicator parameters variable and allow users to adjust them in the UI. Such parameters are called **input parameters** or **inputs**. Users should provide values for the input parameters in the _Inputs_ tab of the indicator settings dialog. Then, these values will be used in the indicator [calculations](#handle-input-values-in-the-constructor). For example, a custom indicator can accept a [source symbol] and length as input parameters. To enable input parameters, you should take the following steps: 1. [Define a list of input parameters](#define-a-list-of-input-parameters) 2. [Specify default values](#specify-default-values) 3. [Handle input values in the constructor](#handle-input-values-in-the-constructor) ## Define a list of input parameters To define a list of input parameters, you should assign an array of objects to the [`inputs`] property in [`StudyMetaInfo`]. ```javascript custom_indicators_getter: function(PineJS) { return Promise.resolve([ // Indicator object { // Define indicator metadata metainfo: { /* Other StudyMetaInfo properties */ // Define input parameters inputs: [ /* A list of input objects */ ] }, } ]); }, ``` :::tip `StudyMetaInfo` is an interface that you should implement to provide metadata for the custom indicator. For more information, refer to the [Metainfo] article. ::: Input parameters can be of multiple types, including numeric, text, time, and others. Therefore, each object in `inputs` should implement a certain interface depending on the parameter type. The table below contains frequently used interfaces: Interface | Definition ---------|---------- [`StudyNumericInputInfo`] | Designed for numeric parameters. [`StudyTextInputInfo`] | Designed for parameters represented with text. For example, types of a smoothing line: SMA, EMA, and WMA. [`StudySourceInputInfo`] | Designed to specify values that are used to calculate the indicator. For example, open or close prices of the bars. [`StudySymbolInputInfo`] | Designed to specify a [source symbol]. Refer to [`StudyInputInfo`](../../api/modules/Charting_Library.md#studyinputinfo) for a complete list of interfaces. Consider the following example. A custom indicator has two input parameters: length (a time period) and source (a type of bar values). To specify these parameters, you should implement a [`StudyNumericInputInfo`] and [`StudySourceInputInfo`] objects, respectively. Both interfaces have the following properties: - `id` that is used to refer to the input parameter - `name` that specifies the parameter name in the _Inputs_ tab - `type` that specifies the parameter data type - `defval` that specifies the default parameter value - `group` that creates a header above all inputs sharing the same `group` string. Refer to [Group inputs](#group-inputs) for more information. Other properties depend on the parameter type. The code sample below shows the implementation of the input parameters. ```javascript metainfo: { // ... inputs: [ // StudyNumericInputInfo object { id: "length", name: "Length", defval: 9, // 9 bars type: "integer", min: 1, max: 10000, }, // StudySourceInputInfo object { id: "source", name: "Source", defval: "close", // Close price type: "source", options: [ // Options in the drop-down menu "open", "high", "low", "close", "hl2", "hlc3", "ohlc4", ], }, ] } ``` ## Specify default values [`StudyMetaInfo`] contains the [`defaults`] property that stores default values for all indicator settings, including input parameters. For each parameter defined in [`inputs`], you should provide the corresponding value in `defaults`. :::warning Your custom indicator will not work unless you provide values in `defaults` for each input parameter. ::: To specify default values, assign a [`StudyInputsSimple`](../../api/interfaces/Charting_Library.StudyInputsSimple.md) object to the `inputs` property in [`StudyDefaults`]. `StudyInputsSimple` contains pairs of keys and values, where a key is a certain input parameter's `id`, and a value is the default value for this parameter. In the [previous section](#define-a-list-of-input-parameters), you can see an example of the indicator with two input parameters: length and source. The code sample below demonstrates how to specify default input values for this indicator. ```javascript metainfo: { // ... inputs: [ { id: "length", // This value is used as ID to refer to the input parameter // ... }, { id: "source", // This value is used as ID to refer to the input parameter // ... }, ] // StudyDefaults object defaults: { // ... inputs: { // ID : default value length: 9, source: "close", }, } } ``` ## Handle input values in the constructor To create a custom indicator, you should implement a [constructor] that calculates indicator data. In the constructor, you can retrieve input values and then use them in your data calculations. To do this, use the `inputCallback` provided with [`main`] and [`init`] functions. The callback returns an array of input values arranged in the same order as in the [`inputs`] property. In the [Define a list of input parameters](#define-a-list-of-input-parameters) section, you can see an example of the indicator with two input parameters: length and source. The code sample below demonstrates how to get input values for this indicator. ```javascript constructor: function () { this.main = function(ctx, inputCallback) { // ... this._input = inputCallback; var length = this._input(0); var source = this._input(1); }; } ``` ## Group inputs You can visually organize input parameters into groups within the _Settings_ dialog by assigning the same `group` string to multiple inputs. The `group` value is displayed as a header above the grouped inputs. ```javascript metainfo: { // ... inputs: [ { id: "fast_length", name: "Fast Length", defval: 12, type: "integer", group: "MACD", }, { id: "slow_length", name: "Slow Length", defval: 26, type: "integer", group: "MACD", }, { id: "signal_length", name: "Signal Smoothing", defval: 9, type: "integer", group: "Signal", }, ] } ``` In the example above, "Fast Length" and "Slow Length" appear under a **MACD** header while "Signal Smoothing" appears under a **Signal** header. [custom indicator]: https://charting-library-docs.xstaging.tv/latest/custom_studies.md [`inputs`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.RawStudyMetaInfo#inputs [source symbol]: https://charting-library-docs.xstaging.tv/latest/resources/glossary.md#source-symbol [`StudyMetaInfo`]: https://charting-library-docs.xstaging.tv/latest/api/modules/Charting_Library#studymetainfo [Metainfo]: https://charting-library-docs.xstaging.tv/latest/custom_studies/metainfo.md [`StudyTextInputInfo`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.StudyTextInputInfo [`StudyNumericInputInfo`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.StudyNumericInputInfo [`StudySourceInputInfo`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.StudySourceInputInfo [`StudySymbolInputInfo`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.StudySymbolInputInfo [`defaults`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.RawStudyMetaInfo#defaults [`StudyDefaults`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.StudyDefaults [constructor]: https://charting-library-docs.xstaging.tv/latest/custom_studies/custom-indicator-constructor.md [`main`]: https://charting-library-docs.xstaging.tv/latest/custom_studies/custom-indicator-constructor.md#main [`init`]: https://charting-library-docs.xstaging.tv/latest/custom_studies/custom-indicator-constructor.md#init --- ## Sitemap - [All documentation pages](https://charting-library-docs.xstaging.tv/llms.txt) - [Full page map with headings](https://charting-library-docs.xstaging.tv/docs_map.md)