# Data mapping & transforming

Sometimes the data returned by a data source or an API is structured not in a proper way for UI Bakery to use it inside components. You may need to reformat your data or enrich it with other properties. You may also need to make some live data calculations before you display it. All this can be achieved with *UI Bakery Actions*.

## Accessing a nested object property

When retrieving a list of items, a lot of APIs may return an object that has a structure similar to this:

```javascript
{
  length: 10,
  records: []
}
```

The actual list here is placed under the nested `records` or another key. If we need to display this list in a Table component, we need to transform it before passing it to the Table.

### Transforming HTTP responses

To transform HTTP responses, we recommend creating a **separate code action step**. In our example here, we want to transform the following object response into an array response:

```javascript
{
allFilms: Object { films: Array[6] }
}
```

We simply need to add a JS code action step to our action and specify the following code:

```javascript
return {{data}}.allFilms.films;
```

{% hint style="info" %}
`{{data}}` in this case represents the result of the HTTP request.
{% endhint %}

<figure><img src="https://837703843-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX6zPRMFFK0yrTghj7cY%2Fuploads%2FsHbJcmba3LATrrZb6gzh%2FCleanShot%202024-11-29%20at%2018.18.01-min%20(1).png?alt=media&#x26;token=8a4ec3ad-63e7-46f3-9ce2-c75d74391321" alt=""><figcaption></figcaption></figure>

Action steps are executed sequentially, which means that any step has access to the result of the previous step execution. The`{{data}}` variable keeps the result and the`{{error}}` variable keeps the caught error that may occur during the step execution.

As a result, the action will return an array of items that can be easily connected to a Table or other components.

## Transforming list object properties

In case you need to transform, rename, or access nested object keys, you can use a **JavaScript** `map` **function**.

For example, your API returns a list of items that have a nested object:

```javascript
[
  {
    id: 25,
    price: 1000,
    user: {
      name: 'John',
      email: 'john@mycompany.com'
    }
  }
]
```

&#x20;But you need a particular property, not the whole entity, so you need it to look like this:

```javascript
[
  {
    id: 25,
    price: 1000,
    name: 'John',
    email: 'john@mycompany.com'
  }
]
```

To transform a list of objects like this, use a separate **code action** step with the following JavaScript function:

```javascript
return {{data}}.map(item => {
  return {
    id: item.id,
    price: item.price,
    name: item.user.name,
    email: item.user.email
  };
});
```

{% @arcade/embed flowId="pnJ6dCjiLv99uCGWZXU1" url="<https://app.arcade.software/share/pnJ6dCjiLv99uCGWZXU1>" %}

You can also use a shorter version. It'll keep the original object but will also copy over the user properties to the first level of the object:

```javascript
return {{data}}.map(item => {
  return {
    ...item,
    ...item.user
  };
});
```

In the same way, you can do calculations, rename properties or add additional fields to the response.

## Loading a single object of the list

When an API returns a list of objects but you need only one object from this list, you can transform it using JavaScript syntax for accessing array objects by object index:

```javascript
return {{data[0]}};
```

<figure><img src="https://837703843-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX6zPRMFFK0yrTghj7cY%2Fuploads%2FX1POPYc7gG0mgMgBWLk4%2FCleanShot%202025-03-17%20at%2017.59.08%402x-min.png?alt=media&#x26;token=4d4f3d96-2c3d-45fc-99c2-9ed6a2941813" alt=""><figcaption></figcaption></figure>

In this case, only the first item of the list will be returned. This is helpful when you are working with an **SQL query** step and you need to receive only one item.

## Receiving the header of the HTTP response

If you need to get the header from the HTTP response, switch the *Transform result* toggle and specify the `{{res}}` variable in the *Modify the result* field. Then, run the action.

<figure><img src="https://837703843-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX6zPRMFFK0yrTghj7cY%2Fuploads%2F4WM2FDQUhZD5oB1TAY4b%2FCleanShot%202025-03-17%20at%2018.02.25%402x-min.png?alt=media&#x26;token=f9545299-c4af-46b8-b090-808ae1008a67" alt=""><figcaption></figcaption></figure>

## Converting JSON into a JavaScript object

If the returned item holds a `string/JSON` representation of your data, you will need to parse it to a JavaScript object (using a `JSON.parse` function) before passing it to UI Bakery components:

```javascript
JSON.parse(data['your_item'])
```

:information\_source: Please note, that `JSON.parse` will fail against some empty values as well as non-valid JSON strings, so the safe statement will look like this:

{% code overflow="wrap" %}

```javascript
const yourItem = data['your_item'] ? JSON.parse(data['your_item']) : {};
```

{% endcode %}

If you are not completely sure whether the server returns a valid JSON string, you can extend it to this version:

```javascript
const yourItem = {};
try {
  yourItem = JSON.parse(data['your_item']);
} catch (e) {}

```


---

# 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://docs.uibakery.io/build-from-scratch/getting-started/transform-data-with-javascript/mapping-and-transforming-data.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.