---
title: The Select2 data format
taxonomy:
    category: docs
---

Select2 can render programmatically supplied data from an array or remote data source (AJAX) as dropdown options. These will be rendered as actual `<option>` elements in the target `<select>` control.

In order to accomplish this, Select2 expects a very specific data format.  This format consists of a JSON object containing an array of objects keyed by the `results` key.

```
{
  "results": [
    {
      "id": 1,
      "text": "Option 1"
    },
    {
      "id": 2,
      "text": "Option 2"
    }
  ],
  "pagination": {
    "more": true
  }
}
```

Each object should contain, _at a minimum_, an `id` and a `text` property. The `text` property will be displayed by default unless you are using `templateResult` and `templateSelection` to customize the way options and selections are rendered.

The response object may also contain pagination data, if you would like to use the "infinite scroll" feature.  This should be specified under the `pagination` key.

Any additional parameters passed in with data objects will be included on the data objects that Select2 exposes.

## Transforming data into the required format

### Generating `id` properties

Select2 requires that the `id` property is used to uniquely identify the options that are displayed in the results list. If you use a property other than `id` (like `pk`) to uniquely identify an option, you need to map your old property to `id` before passing it to Select2.

If you cannot do this on your server or you are in a situation where the API cannot be changed, you can do this in JavaScript before passing it to Select2:

```
var data = $.map(yourArrayData, function (obj) {
  obj.id = obj.id || obj.pk; // replace pk with your identifier

  return obj;
});
```

### Generating `text` properties

Just like with the `id` property, Select2 requires that the text that should be displayed for an option is stored in the `text` property. You can map this property from any existing property using the following JavaScript:

```
var data = $.map(yourArrayData, function (obj) {
  obj.text = obj.text || obj.name; // replace name with the property used for the text

  return obj;
});
```

## Automatic string casting

Because the `value` attribute on a `<select>` tag must be a string, and Select2 generates the `value` attribute from the `id` property of the data objects, the `id` property on each data object must also be a string.

Select2 will attempt to convert anything that is not a string to a string, which will work for most situations, but it is recommended to explicitly convert your `id`s to strings ahead of time.

Blank `id`s or an `id` with a value of `0` are not permitted.

## Grouped options

When options are to be generated in `<optgroup>` sections, options should be nested under the `children` key of each group object.  The label for the group should be specified as the `text` property on the group's corresponding data object.

```
{
  "results": [
    { 
      "text": "Group 1", 
      "children" : [
        {
            "id": 1,
            "text": "Option 1.1"
        }
        {
            "id": 2,
            "text": "Option 1.2"
        }
      ]
    },
    { 
      "text": "Group 2", 
      "children" : [
        {
            "id": 3,
            "text": "Option 2.1"
        }
        {
            "id": 4,
            "text": "Option 2.2"
        }
      ]
    }
  ],
  "paginate": {
    "more": true
  }
}
```

>>>> Because Select2 generates an `<optgroup>` when creating nested options, only [a single level of nesting is supported](/dropdown/option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.