select2/pages/09.data-sources/01.formats/docs.md

title	taxonomy
The Select2 data format	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 ids to strings ahead of time.

Blank ids 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. Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.