Use the `opinionScale()` function to create opinion scale inputs in your forms. It allows users to provide ratings or opinions on a numeric scale with optional labels at the start and end points. When using the default parameter values, the opinion scale is a [Net Promoter Score®](https://en.wikipedia.org/wiki/Net_promoter_score).
***
## Basic usage
```javascript
import { Composer } from "formsmd";
const composer = new Composer({
id: "my-form"
});
composer.opinionScale("agreement", {
question: "How much do you agree with this statement?"
});
```
Generates the following Markdown-like syntax:
```
#! id = my-form
agreement = OpinionScale(
| question = How much do you agree with this statement?
)
```
### Required
Add the `required` parameter to make the field mandatory:
```javascript
composer.opinionScale("agreement", {
question: "How much do you agree with this statement?",
required: true
});
```
Generates the following Markdown-like syntax:
```
agreement* = OpinionScale(
| question = How much do you agree with this statement?
)
```
***
## Function overview
The following is the overview of the function:
```typescript
opinionScale(name: string, params: object)
```
### Arguments
| Name | Type | Description |
| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | `string` | A unique name for your form field that you'll use to identify the user's response.\* |
| `params` | `object` | An object containing all the configuration parameters for your opinion scale field (see the [parameters section](#parameters) below for the full list of options). |
{% hint style="danger" %} \*Avoid values for the `name` argument which may be the names of HTML attributes, such as `"name"`, `"role"`, `"id"`, etc. This is because by default, the form's template string is first sanitized using [DOMPurify](https://github.com/cure53/DOMPurify), and these values may be removed to prevent DOM clobbering.
{% endhint %}
***
## Parameters
### Shared parameters
These parameters are common to all form fields:
| Name | Type | Description |
| --------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `question` (required) | `string` | The main question or label of the form field. |
| `required` | `true` (`boolean`) | When set, the field becomes required. |
| `description` | `string` | Any extra information that the user may need to fill out the form. Appears right below the question. |
| `fieldSize` | `"sm"` | When set to `"sm"`, the font sizes of the question, description, and answer are made smaller. |
| `labelStyle` | `"classic"` | When set to `"classic"`, the question and description of the form field are made smaller. |
| `subfield` | `true` (`boolean`) | When set, the question and description of the form field are made smaller. Functionally the same as setting `labelStyle` to `"classic"`. |
| `disabled` | `true` (`boolean`) | When set, the input is disabled. |
| `autofocus` | `true` (`boolean`) | When set, the input will be automatically focused when the parent slide becomes active, or immediately after page load. |
| `id` | `string` | The `id` attribute of the form field container. |
| `classNames` | `string[]` | The CSS class names of the form field. [See the available CSS utility classes](https://docs.forms.md/content/css-utility-classes). |
| `attrs` | `Array<{ name: string, value: string }>` | Other HTML attributes of the form field. Each attribute has a `name` and `value` property. |
| `displayCondition` | `{ dependencies: string[], condition: string }` | Controls when the field is shown. The `dependencies` lists the fields to watch, and `condition` is the expression that must be true to show the field. The `condition` must be a valid [Nunjucks](https://mozilla.github.io/nunjucks/) expression. [See example](#conditional-display). |
### Opinion scale specific parameters
| Name | Type | Description |
| ---------------- | ------------------ | ---------------------------------------------- |
| `startAt` | `number` | Starting number (`0` or `1`). Defaults to `0`. |
| `outOf` | `number` | Maximum scale value (5-10). Defaults to `10`. |
| `labelStart` | `string` | Label for the start of the scale. |
| `labelEnd` | `string` | Label for the end of the scale. |
| `hideLabelStart` | `true` (`boolean`) | Whether to hide the start label. |
| `hideLabelEnd` | `true` (`boolean`) | Whether to hide the end label. |
| `value` | `number` | Pre-selected value. |
***
## Examples
### Opinion scale with custom range and labels
```javascript
composer.opinionScale("satisfaction", {
question: "How likely are you to recommend our product?",
description: "0 means not likely, 5 means very likely",
startAt: 0,
outOf: 5,
labelStart: "Not likely",
labelEnd: "Very likely",
required: true
});
```
Generates the following Markdown-like syntax:
```
satisfaction* = OpinionScale(
| question = How likely are you to recommend our product?
| description = 0 means not likely, 5 means very likely
| startAt = 0
| outOf = 5
| labelStart = Not likely
| labelEnd = Very likely
)
```
### Opinion scale with hidden labels
```javascript
composer.opinionScale("rating", {
question: "Rate your experience",
outOf: 5,
startAt: 1,
hideLabelStart: true,
hideLabelEnd: true
});
```
Generates the following Markdown-like syntax:
```
rating = OpinionScale(
| question = Rate your experience
| outOf = 5
| startAt = 1
| hideLabelStart
| hideLabelEnd
)
```
### Styled opinion scale with custom attributes
Add CSS classes and other HTML attributes using the `classNames` and `attrs` parameters. Please note, these class names and attributes are added to the `
