AJAX

DotSelect has built-in support for loading options from a remote server via AJAX. Configure everything through data attributes — no JavaScript needed.

Basic AJAX Select

Point data-ajax-url to your API endpoint:

<select
  data-dot-select
  data-searchable="true"
  data-ajax-url="/api/users?q={@term}"
  data-placeholder="Search users..."
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-searchable="true"
      data-ajax-url="/api/users?q={@term}"
      data-placeholder="Search users..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-searchable="true"
    data-ajax-url="/api/users?q={@term}"
    data-placeholder="Search users..."
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

When the user types in the search box, DotSelect replaces {@term} with the search query and fetches results from the URL.

Token System

DotSelect uses a token system to build dynamic URLs. Tokens are placeholders wrapped in {@...} that get replaced at request time.

Token	Description	Example
{@term}	The current search query typed by the user	?q={@term}
{@page}	The current page number (for pagination)	?page={@page}
{@selected}	Comma-separated list of currently selected values	?exclude={@selected}
{@val}	The current value of the select	?current={@val}
{@pagination_limit}	The number of results per page	?limit={@pagination_limit}

Token Usage Examples

<!-- Basic search -->
<select
  data-dot-select
  data-ajax-url="/api/search?q={@term}"
  data-searchable="true"
>
</select>

<!-- Search with pagination -->
<select
  data-dot-select
  data-ajax-url="/api/users?search={@term}&page={@page}&per_page={@pagination_limit}"
  data-searchable="true"
  data-pagination="true"
  data-pagination-limit="20"
>
</select>

<!-- Exclude already-selected values -->
<select
  data-dot-select
  data-ajax-url="/api/tags?q={@term}&exclude={@selected}"
  data-searchable="true"
  multiple
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <!-- Basic search -->
    <select
      data-dot-select
      data-ajax-url="/api/search?q={@term}"
      data-searchable="true"
    >
    </select>
    
    <!-- Search with pagination -->
    <select
      data-dot-select
      data-ajax-url="/api/users?search={@term}&page={@page}&per_page={@pagination_limit}"
      data-searchable="true"
      data-pagination="true"
      data-pagination-limit="20"
    >
    </select>
    
    <!-- Exclude already-selected values -->
    <select
      data-dot-select
      data-ajax-url="/api/tags?q={@term}&exclude={@selected}"
      data-searchable="true"
      multiple
    >
    </select>
  )
}

<template>
  <!-- Basic search -->
  <select
    data-dot-select
    data-ajax-url="/api/search?q={@term}"
    data-searchable="true"
  >
  </select>
  
  <!-- Search with pagination -->
  <select
    data-dot-select
    data-ajax-url="/api/users?search={@term}&page={@page}&per_page={@pagination_limit}"
    data-searchable="true"
    data-pagination="true"
    data-pagination-limit="20"
  >
  </select>
  
  <!-- Exclude already-selected values -->
  <select
    data-dot-select
    data-ajax-url="/api/tags?q={@term}&exclude={@selected}"
    data-searchable="true"
    multiple
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Field Mapping

By default, DotSelect expects each result object to have id and text fields. If your API returns different field names, use mapping attributes:

<select
  data-dot-select
  data-ajax-url="/api/products?q={@term}"
  data-searchable="true"
  data-option-id="product_id"
  data-option-text="product_name"
  data-placeholder="Search products..."
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('#product_id')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/products?q={@term}"
      data-searchable="true"
      data-option-id="product_id"
      data-option-text="product_name"
      data-placeholder="Search products..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/products?q={@term}"
    data-searchable="true"
    data-option-id="product_id"
    data-option-text="product_name"
    data-placeholder="Search products..."
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Attribute	Description	Default
data-option-id	The field name to use as the option value	id
data-option-text	The field name to use as the option label	text
data-option-disabled	The field name to determine if an option is disabled	disabled
data-option-group	The field name for grouping options	group

Nested Field Paths

You can use dot notation for nested fields:

<select
  data-dot-select
  data-ajax-url="/api/employees?q={@term}"
  data-option-id="employee.id"
  data-option-text="employee.full_name"
  data-searchable="true"
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('#employee.id')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/employees?q={@term}"
      data-option-id="employee.id"
      data-option-text="employee.full_name"
      data-searchable="true"
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/employees?q={@term}"
    data-option-id="employee.id"
    data-option-text="employee.full_name"
    data-searchable="true"
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Response Format

DotSelect expects the API response to be JSON. By default, it looks for an array of objects at the root level or inside a data key:

// Root-level array
[
  { "id": 1, "text": "Alice" },
  { "id": 2, "text": "Bob" }
]

// Nested under "data" key
{
  "data": [
    { "id": 1, "text": "Alice" },
    { "id": 2, "text": "Bob" }
  ]
}

If your results are nested under a different key, specify it with data-ajax-data-key:

<select
  data-dot-select
  data-ajax-url="/api/users?q={@term}"
  data-ajax-data-key="results.items"
  data-searchable="true"
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/users?q={@term}"
      data-ajax-data-key="results.items"
      data-searchable="true"
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/users?q={@term}"
    data-ajax-data-key="results.items"
    data-searchable="true"
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

AJAX Configuration Attributes

Attribute	Description	Default
data-ajax-url	The URL to fetch data from (supports tokens)	—
data-ajax-method	HTTP method	GET
data-ajax-delay	Debounce delay in ms before sending request	300
data-ajax-min-chars	Minimum characters before triggering search	1
data-ajax-data-key	Key path to the results array in the response	data
data-ajax-cache	Cache AJAX results	true
data-ajax-headers	JSON string of custom request headers	{}

Custom Headers

Send authentication tokens or custom headers with your requests:

<select
  data-dot-select
  data-ajax-url="/api/secure/users?q={@term}"
  data-ajax-headers='{"Authorization": "Bearer YOUR_TOKEN", "X-Custom": "value"}'
  data-searchable="true"
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/secure/users?q={@term}"
      data-ajax-headers='{"Authorization": "Bearer YOUR_TOKEN", "X-Custom": "value"}'
      data-searchable="true"
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/secure/users?q={@term}"
    data-ajax-headers='{"Authorization": "Bearer YOUR_TOKEN", "X-Custom": "value"}'
    data-searchable="true"
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Templates

Customize how options and selected items are displayed with template attributes. Templates use token syntax to reference fields from the data:

<select
  data-dot-select
  data-ajax-url="/api/users?q={@term}"
  data-searchable="true"
  data-template-option="<div class='user-option'><img src='{@avatar}' /><span>{@text}</span><small>{@email}</small></div>"
  data-template-item="<span><img src='{@avatar}' class='avatar-sm' /> {@text}</span>"
  data-placeholder="Search users..."
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/users?q={@term}"
      data-searchable="true"
      data-template-option="<div class='user-option'><img src='{@avatar}' /><span>{@text}</span><small>{@email}</small></div>"
      data-template-item="<span><img src='{@avatar}' class='avatar-sm' /> {@text}</span>"
      data-placeholder="Search users..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/users?q={@term}"
    data-searchable="true"
    data-template-option="<div class='user-option'><img src='{@avatar}' /><span>{@text}</span><small>{@email}</small></div>"
    data-template-item="<span><img src='{@avatar}' class='avatar-sm' /> {@text}</span>"
    data-placeholder="Search users..."
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Available Template Attributes

Attribute	Description
data-template-option	Template for each option in the dropdown
data-template-item	Template for selected items (displayed in the control)
data-template-no-results	Template shown when no results are found
data-template-loading	Template shown while loading AJAX results

TIP

Template tokens correspond to fields in your API response. Any field returned by the API can be used as a {@field_name} token in templates.

Pagination

Enable infinite-scroll pagination for large datasets:

<select
  data-dot-select
  data-ajax-url="/api/users?q={@term}&page={@page}&limit={@pagination_limit}"
  data-searchable="true"
  data-pagination="true"
  data-pagination-limit="25"
  data-placeholder="Search users..."
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/users?q={@term}&page={@page}&limit={@pagination_limit}"
      data-searchable="true"
      data-pagination="true"
      data-pagination-limit="25"
      data-placeholder="Search users..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/users?q={@term}&page={@page}&limit={@pagination_limit}"
    data-searchable="true"
    data-pagination="true"
    data-pagination-limit="25"
    data-placeholder="Search users..."
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

DotSelect automatically detects whether more pages are available. Your API response should include pagination metadata:

{
  "data": [
    { "id": 1, "text": "Alice" },
    { "id": 2, "text": "Bob" }
  ],
  "pagination": {
    "more": true
  }
}

Or specify a custom key for the "has more" flag:

<select
  data-dot-select
  data-ajax-url="/api/users?q={@term}&page={@page}"
  data-pagination="true"
  data-pagination-more-key="meta.has_next_page"
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/users?q={@term}&page={@page}"
      data-pagination="true"
      data-pagination-more-key="meta.has_next_page"
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/users?q={@term}&page={@page}"
    data-pagination="true"
    data-pagination-more-key="meta.has_next_page"
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Attribute	Description	Default
data-pagination	Enable pagination	false
data-pagination-limit	Number of results per page	20
data-pagination-more-key	Key path in response indicating more pages exist	pagination.more

Resolve Mode (Pre-selected AJAX Values)

When using AJAX with pre-selected values, DotSelect needs to resolve those values into display text. Use data-selected to specify pre-selected values that should be fetched from the server:

<select
  data-dot-select
  data-ajax-url="/api/users?q={@term}"
  data-searchable="true"
  data-selected="42,87"
  data-ajax-resolve-url="/api/users/resolve?ids={@selected}"
  data-placeholder="Search users..."
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-ajax-url="/api/users?q={@term}"
      data-searchable="true"
      data-selected="42,87"
      data-ajax-resolve-url="/api/users/resolve?ids={@selected}"
      data-placeholder="Search users..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-ajax-url="/api/users?q={@term}"
    data-searchable="true"
    data-selected="42,87"
    data-ajax-resolve-url="/api/users/resolve?ids={@selected}"
    data-placeholder="Search users..."
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

On initialization, DotSelect calls the resolve URL with the pre-selected IDs to fetch their display text.

WARNING

Without data-ajax-resolve-url, pre-selected values in AJAX mode will show the raw value instead of the display text. Always provide a resolve endpoint when using data-selected with AJAX.

Resolve Configuration

Attribute	Description	Default
data-selected	Comma-separated IDs to pre-select	—
data-ajax-resolve-url	URL to resolve selected IDs to full objects	—

Full AJAX Example

A complete example with search, pagination, templates, and pre-selected values:

<select
  data-dot-select
  data-searchable="true"
  data-ajax-url="/api/employees?search={@term}&page={@page}&limit={@pagination_limit}&exclude={@selected}"
  data-ajax-resolve-url="/api/employees/resolve?ids={@selected}"
  data-ajax-delay="250"
  data-ajax-min-chars="2"
  data-option-id="emp_id"
  data-option-text="full_name"
  data-template-option="<div class='emp-row'><img src='{@photo}' class='emp-photo'/><div><strong>{@full_name}</strong><br/><small>{@department} &middot; {@title}</small></div></div>"
  data-template-item="<span>{@full_name}</span>"
  data-pagination="true"
  data-pagination-limit="15"
  data-selected="101,205"
  data-placeholder="Search employees..."
  data-allow-clear="true"
  multiple
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('#emp_id')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-searchable="true"
      data-ajax-url="/api/employees?search={@term}&page={@page}&limit={@pagination_limit}&exclude={@selected}"
      data-ajax-resolve-url="/api/employees/resolve?ids={@selected}"
      data-ajax-delay="250"
      data-ajax-min-chars="2"
      data-option-id="emp_id"
      data-option-text="full_name"
      data-template-option="<div class='emp-row'><img src='{@photo}' class='emp-photo'/><div><strong>{@full_name}</strong><br/><small>{@department} &middot; {@title}</small></div></div>"
      data-template-item="<span>{@full_name}</span>"
      data-pagination="true"
      data-pagination-limit="15"
      data-selected="101,205"
      data-placeholder="Search employees..."
      data-allow-clear="true"
      multiple
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-searchable="true"
    data-ajax-url="/api/employees?search={@term}&page={@page}&limit={@pagination_limit}&exclude={@selected}"
    data-ajax-resolve-url="/api/employees/resolve?ids={@selected}"
    data-ajax-delay="250"
    data-ajax-min-chars="2"
    data-option-id="emp_id"
    data-option-text="full_name"
    data-template-option="<div class='emp-row'><img src='{@photo}' class='emp-photo'/><div><strong>{@full_name}</strong><br/><small>{@department} &middot; {@title}</small></div></div>"
    data-template-item="<span>{@full_name}</span>"
    data-pagination="true"
    data-pagination-limit="15"
    data-selected="101,205"
    data-placeholder="Search employees..."
    data-allow-clear="true"
    multiple
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>