# JavaScript Utilities

## Introduction

The Form.io Utilities class is a part of the JavaScript SDK, but provides a number of methods that makes working with Form.io forms within your applications easier.

## Installation

To install the Utilities, you can either import them directly into your application as follows.

```
import Utils from 'formiojs/utils';
```

or they can be used as part of the Form.io renderer by including the following script in your application.

```
<script src="https://cdn.form.io/formiojs/formio.form.min.js"></script>
```

{% hint style="info" %}
Navigate to the following link for more information about the [**Form.io CDNs**](https://help.form.io/faq/faq#what-are-the-form.io-cdns)
{% endhint %}

and then you can find the Utilities methods as part of the `Utils` property on the `Formio` object.

```
Formio.Utils.eachComponent(....)
```

## Utility Functions

The following are common functions that can be used within the Form.io Utilities library.

### `eachComponent(components, fn, [includeAll])`

Calls `fn(component)` for each component in `components`, accounting for nested layout components. (Does not call for layout components themselves, unless includeAll is true).

| Parameter  | Description                                                                          |
| ---------- | ------------------------------------------------------------------------------------ |
| components | An array of JSON form components to iterate over.                                    |
| fn         | The function to call for each input component.                                       |
| includeAll | Boolean to indicate if we should include all components including layout components. |

The current data path of the element. Example: data.user.firstName

```
var utils = require('formiojs/utils');
utils.eachComponent(form.components, function(component) {
  // Do something...
})
```

### `getComponent(components, key)`

Returns the component with the given `key` or undefined if not found.

| Parameter  | Description                                          |
| ---------- | ---------------------------------------------------- |
| components | An array of JSON form components to iterate over.    |
| key        | The key of the component you would like to retrieve. |

```
var utils = require('formiojs/utils');
var component = utils.getComponent(form.components, 'myKey');
```

### `findComponents(components, query)`

Returns an array of components that match the find query criteria. This query is very similar to MongoDB where if you wish to find a nested query, you would provide the key as the path of the property using dot notation.&#x20;

| Parameter  | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| components | An array of JSON form components to iterate over.                          |
| query      | A JSON object to use as a query to find a certain component within a form. |

Here is an example.

```
// Find all textfields with a specific custom property.
var utils = require('formiojs/utils');
var comps = utils.findComponents(form.components, {
  'type': 'textfield',
  'properties.objectId': '2345'
});

// Should return all textfield components with 'properties.objectId' = '2345'.
console.log(comps);
```

### `searchComponents(components, query)`

Finds a component provided a query of properties of that component.

| Parameter  | Description                                       |
| ---------- | ------------------------------------------------- |
| components | An array of JSON form components to iterate over. |
| query      | The query to pass to `matchComponent`.            |

### `matchComponent(component, query)`

Matches if a component matches the query.

| Parameter | Description                                               |
| --------- | --------------------------------------------------------- |
| component | A component JSON you would like to match against a query. |
| query     | A JSON query to use as the match query.                   |

```
const component = {
    type: 'textfield',
    key: 'firstName',
    label: 'First Name'
};
if (utils.matchComponent(component, {
    key: 'firstName
}) {
    console.log('The component matches!!');
}
```

###

### `flattenComponents(components, includeAll)`

Returns a key-value object where the keys are the keys for each component in `components` and each key points to the corresponding component. This includes nested components as well. Pass true for includeAll if you want to include layout components.

| Parameter  | Description                                                                            |
| ---------- | -------------------------------------------------------------------------------------- |
| components | An array of JSON form components to iterate over.                                      |
| includeAll | Boolean to indicate if you wish to include all components including layout components. |

```
var utils = require('formiojs/utils');
var flattened = utils.flattenComponents(form.components);
console.log(flattened['myNestedComponent']);
```

### `isLayoutComponent(component)`

Determine if a component is a layout component.

| Parameter | Description                                                   |
| --------- | ------------------------------------------------------------- |
| component | The component JSON to determine if this is a layout component |

```
var utils = require('formiojs/utils');
var layoutComponent = utils.isLayoutComponent(form.components[0]);
console.log(layoutComponent);
```

### `getValue(submission, key)`

Get the value for a components API key, from the given submission. Recursively searches the submission for the key.

| Parameter  | Description                                                                     |
| ---------- | ------------------------------------------------------------------------------- |
| submission | The submission JSON object                                                      |
| key        | The component key you would like to fetch the value from within the submission. |

```
var utils = require('formiojs/utils');
var value = utils.getValue(submission, 'myComponent'); // The value or undefined.
```

### `parseFloat(value)`

Extension of standard [**parseFloat**](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/parseFloat) function, that also clears input string. Useful for [**Currency component**](https://help.form.io/userguide/form-components/#currency).

| Parameter | Description                        |
| --------- | ---------------------------------- |
| value     | The value you would like to parse. |

```
utils.parseFloat('12,345,678.90'); // -> 12345678.90
```

### `formatAsCurrency(value)`

Formats provided value in way how [**Currency component**](https://help.form.io/userguide/form-components/#currency) uses it.

| Parameter | Description                         |
| --------- | ----------------------------------- |
| value     | The value you would like to format. |

```
utils.formatAsCurrency(123.4); // -> '123.40'
utils.formatAsCurrency(12345678.9); // -> '12,345,678.90'
utils.formatAsCurrency(12345678.915); // -> '12,345,678.92'
utils.formatAsCurrency('12345678.915'); // -> '12,345,678.92'
```

### `escapeRegExCharacters(value)`

Escapes RegEx characters in provided String value.

| Parameter | Description                                                   |
| --------- | ------------------------------------------------------------- |
| value     | The value you would like to escape the regex characters from. |

```
utils.escapeRegExCharacters('[form.io](https://form.io/)'); // -> '\[form\.io\]\(https:\/\/form\.io\)'
```

### `boolValue(value)`

Determines the boolean value of a setting.

### `isMongoId(text)`

Check to see if an ID is a mongoID.

### `checkCondition(component, row, data, form, instance)`

Checks the conditions for a provided component and data.

| Parameter | Description                                                |
| --------- | ---------------------------------------------------------- |
| component | The component JSON                                         |
| row       | Contextual row data                                        |
| data      | Full submission data                                       |
| form      | The form JSON schema                                       |
| instance  | The component instance this method is being executed with. |

### `unescapeHTML(str)`

Unescape HTML characters like <, >, & and etc.

### `convertStringToHTMLElement(str, selector)`

Make HTML element from string

### `guid()`

Generate a GUID

### `isValidDate(date)`

Checks a date to see if it is valid.

### `formatDate(value, format, timezone, flatPickrInputFormat)`

Format a date provided a value, format, and timezone object.

### `getBrowserInfo()`

Get the browser name and version

### `isInputComponent(componentJson)`

Checks to see if a component JSON is an input component.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.form.io/developers/javascript-development/javascript-utilities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.