# Currency

> A Currency widget to allow user to enter monetary values

Currency widgets are [Input Fields](https://golemui.com/dx/widgets-reference/input-fields/overview.md) that allow the user to enter monetary values, displaying a formatted currency string over the input when inactive.


```ts title="currency.ts"

export default [
  gui.inputs.currency('price', {
    label: 'Price',
  }),
];
```

_Live demo on the docs page. Form definition: [currency.ts](https://golemui.com/template/widgets-dx/currency/currency.ts)._

## Props

Use these `props` to customize your Currency widget.

| prop                    | type   | description                                                                      |
| ----------------------- | ------ | -------------------------------------------------------------------------------- |
| `autocomplete`          | string | `'on'`, `'off'`, or a space-separated list of W3C autofill tokens                |
| `currency`              | string | The ISO 4217 currency code (e.g., `USD`, `EUR`) to format the number as currency |
| `hint`                  | string | A description to display below the currency input                                |
| `icon`                  | string | A css class to display an icon inside the input                                  |
| `maximumFractionDigits` | number | Maximum number of decimal places to include in the formatted string              |
| `minimumFractionDigits` | number | Minimum number of decimal places to include in the formatted string              |
| `placeholder`           | string | A placeholder text to display when the currency input has no value               |
| `step`                  | number | Numeric step size for user input                                                 |

### Placeholder

Use the property `placeholder` to add a placeholder.


```ts title="currency.ts"

export default [
  gui.inputs.currency('price', {
    placeholder: 'Enter the amount',
    label: 'Price',
  }),
];
```

_Live demo on the docs page. Form definition: [currency-placeholder.ts](https://golemui.com/template/widgets-dx/currency/currency-placeholder.ts)._

### Hint

<Aside>A `label` is required for the `hint` to be displayed.</Aside>

Use the property `hint` to add a description.


```ts title="currency.ts"

export default [
  gui.inputs.currency('price', {
    hint: 'Please enter the price in USD.',
    label: 'Price',
  }),
];
```

_Live demo on the docs page. Form definition: [currency-hint.ts](https://golemui.com/template/widgets-dx/currency/currency-hint.ts)._

### Icon

Use the property `icon` to add an icon to the widget. The value of `icon` represents a set of CSS classes separated by spaces. The icon is displayed inside the input field.


```ts title="currency.ts"

export default [
  gui.inputs.currency('price', {
    icon: 'attach_money',
    label: 'Price',
  }),
];
```

_Live demo on the docs page. Form definition: [currency-icon.ts](https://golemui.com/template/widgets-dx/currency/currency-icon.ts)._

### Currency & Decimal Formatting

Use the properties `currency`, `minimumFractionDigits`, and `maximumFractionDigits` to tightly control how the monetary value is parsed and formatted when not actively being edited. Without them, the field uses the decimals of the currency: 2 for `USD`, 0 for `JPY`, 3 for `KWD`.


```ts title="currency.ts"

export default [
  gui.inputs.currency('price', {
    currency: 'EUR',
    minimumFractionDigits: 2,
    maximumFractionDigits: 4,
    label: 'Price (EUR)',
  }),
];
```

_Live demo on the docs page. Form definition: [currency-format.ts](https://golemui.com/template/widgets-dx/currency/currency-format.ts)._

### Precision

Use the properties `minimumFractionDigits` and `maximumFractionDigits` to specify the exact number of decimal places for the formatted currency display.


```ts title="currency.ts"

export default [
  gui.inputs.currency('price_high', {
    currency: 'USD',
    minimumFractionDigits: 4,
    maximumFractionDigits: 6,
    label: 'High Precision (4-6 digits)',
    uid: 'currency-precision-high',
  }),
  gui.inputs.currency('price_low', {
    currency: 'USD',
    minimumFractionDigits: 0,
    maximumFractionDigits: 0,
    label: 'No Decimals',
    uid: 'currency-precision-low',
  }),
];
```

_Live demo on the docs page. Form definition: [currency-precision.ts](https://golemui.com/template/widgets-dx/currency/currency-precision.ts)._

### Step

Use the `step` property to define the increment size for numeric input via keyboard (arrows) or browser controls.


```ts title="currency.ts"

export default [
  gui.inputs.currency('amount', {
    currency: 'USD',
    step: 5.5,
    label: 'Amount (Step 5.50)',
    uid: 'currency-step',
  }),
];
```

_Live demo on the docs page. Form definition: [currency-step.ts](https://golemui.com/template/widgets-dx/currency/currency-step.ts)._

## Styling

Currency inputs can be styled as explained in the [Styling Guide](https://golemui.com/dx/styling/overview.md).

### CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

| CSS Variable           | Description                                |
| ---------------------- | ------------------------------------------ |
| `--gui-bg-default`     | Formatted value text background over input |
| `--gui-font-sm`        | Formatted value text and hint font size    |
| `--gui-space-10`       | Icon left padding or inline-start space    |
| `--gui-intent-error`   | Border and text color when invalid         |
| `--gui-radius-md`      | Input radius                               |
| `--gui-border-default` | Input border color                         |
| `--gui-bg-surface`     | Input background color                     |
| `--gui-text-default`   | Input text color                           |

### Anatomy

This is the anatomy of the Currency Widget in case you want to use your CSS styles.


```html title="currency-anatomy.html"
<gui-currency-input class="gui-currency gui-field">
  <gui-currency class="gui-field">
    <label class="gui-label" for="fieldUid" id="fieldUid_label">
      <span class="gui-label__text">Label</span>
      <div class="gui-widget-hint" id="fieldUid_hint" aria-hidden="true">Hint</div>
    </label>

    <div class="gui-widget">
      <input
        type="number"
        inputmode="decimal"
        step="any"
        id="fieldUid"
        class="gui-widget-input gui-currency--icon"
        placeholder="Custom placeholder"
        aria-describedby="fieldUid_hint"
      />
      <span aria-hidden="true" class="gui-currency__format-value gui-currency__format-value--icon">
        $1,111.10
      </span>
      <span aria-hidden="true" class="gui-widget-icon attach_money" data-icon="attach_money"></span>
    </div>

    <div class="gui-validator gui-validator--empty" id="fieldUid_errors" role="alert"></div>
  </gui-currency>
</gui-currency-input>
```
