Tagging

DotSelect supports tagging — allowing users to create new options on the fly by typing values that do not exist in the dropdown.

Enabling Tagging

Add data-create-items="true" to allow users to type and create new options:

<select
  data-dot-select
  data-searchable="true"
  data-create-items="true"
  multiple
  data-placeholder="Type to add tags..."
>
  <option value="html">HTML</option>
  <option value="css">CSS</option>
  <option value="js">JavaScript</option>
</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-create-items="true"
      multiple
      data-placeholder="Type to add tags..."
    >
      <option value="html">HTML</option>
      <option value="css">CSS</option>
      <option value="js">JavaScript</option>
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-searchable="true"
    data-create-items="true"
    multiple
    data-placeholder="Type to add tags..."
  >
    <option value="html">HTML</option>
    <option value="css">CSS</option>
    <option value="js">JavaScript</option>
  </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 a value that does not match any existing option, an "Add ..." prompt appears in the dropdown. Pressing Enter or clicking the prompt adds the new value.

How the "Add..." Prompt Works

1. The user types into the search input
2. DotSelect filters existing options as usual
3. If no exact match is found and data-create-items is enabled, an "Add ..." option appears at the bottom of the dropdown
4. Clicking the prompt (or pressing Enter) creates a new <option> element and selects it
5. The new option's value and text are both set to the typed string

Customizing the Prompt Text

Use the locale system to customize the "Add" prompt:

<select
  data-dot-select
  data-searchable="true"
  data-create-items="true"
  data-create-items-text="Create: {@term}"
  multiple
  data-placeholder="Add skills..."
>
</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-create-items="true"
      data-create-items-text="Create: {@term}"
      multiple
      data-placeholder="Add skills..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-searchable="true"
    data-create-items="true"
    data-create-items-text="Create: {@term}"
    multiple
    data-placeholder="Add skills..."
  >
  </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>

The {@term} token is replaced with what the user typed.

Tags Plugin

For a more polished tagging experience, enable the tags plugin. This adds comma-separated input and paste support:

<select
  data-dot-select
  data-searchable="true"
  data-create-items="true"
  data-plugins="tags"
  multiple
  data-placeholder="Enter tags separated by commas..."
>
</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-create-items="true"
      data-plugins="tags"
      multiple
      data-placeholder="Enter tags separated by commas..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-searchable="true"
    data-create-items="true"
    data-plugins="tags"
    multiple
    data-placeholder="Enter tags separated by commas..."
  >
  </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>

Comma Separator

With the tags plugin, users can type multiple values separated by commas. Each segment becomes a separate tag:

javascript, python, rust

This creates three separate tags: javascript, python, and rust.

Custom Separator

Change the separator character using data-tags-separator:

<select
  data-dot-select
  data-create-items="true"
  data-plugins="tags"
  data-tags-separator=";"
  multiple
  data-placeholder="Separate with semicolons..."
>
</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-create-items="true"
      data-plugins="tags"
      data-tags-separator=";"
      multiple
      data-placeholder="Separate with semicolons..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-create-items="true"
    data-plugins="tags"
    data-tags-separator=";"
    multiple
    data-placeholder="Separate with semicolons..."
  >
  </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>

Paste Support

The tags plugin supports pasting comma-separated (or custom-separated) values. When a user pastes text like:

react, vue, angular, svelte

DotSelect automatically splits the pasted text by the separator and creates individual tags for each value.

TIP

Paste support works from spreadsheets too. If a user copies a column of cells from Excel or Google Sheets, each cell value becomes a separate tag.

Validation and Duplicates

DotSelect prevents duplicate tags by default. If the user tries to add a tag that already exists, it is ignored.

Restricting Allowed Values

Combine data-create-items with data-create-items-pattern to validate new tags against a regex pattern:

<select
  data-dot-select
  data-create-items="true"
  data-create-items-pattern="^[a-zA-Z0-9_-]+$"
  data-plugins="tags"
  multiple
  data-placeholder="Alphanumeric tags only..."
>
</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-create-items="true"
      data-create-items-pattern="^[a-zA-Z0-9_-]+$"
      data-plugins="tags"
      multiple
      data-placeholder="Alphanumeric tags only..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-create-items="true"
    data-create-items-pattern="^[a-zA-Z0-9_-]+$"
    data-plugins="tags"
    multiple
    data-placeholder="Alphanumeric tags only..."
  >
  </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>

If the typed value does not match the pattern, the "Add" prompt does not appear.

Combining with AJAX

Tagging can be combined with AJAX search. Users can search existing server-side options and create new ones:

<select
  data-dot-select
  data-searchable="true"
  data-create-items="true"
  data-ajax-url="/api/tags?q={@term}"
  data-plugins="tags"
  multiple
  data-placeholder="Search or create tags..."
>
</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-create-items="true"
      data-ajax-url="/api/tags?q={@term}"
      data-plugins="tags"
      multiple
      data-placeholder="Search or create tags..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-searchable="true"
    data-create-items="true"
    data-ajax-url="/api/tags?q={@term}"
    data-plugins="tags"
    multiple
    data-placeholder="Search or create tags..."
  >
  </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>

WARNING

When using tagging with AJAX, newly created tags exist only on the client. Your form submission handler should be prepared to handle new values that do not yet exist in the database.

Styling Tags

Tags inherit the default DotSelect item styling. Customize their appearance with CSS:

.dot-select .ds-item {
  background-color: #e0f2fe;
  border: 1px solid #7dd3fc;
  border-radius: 9999px;
  padding: 2px 8px;
  font-size: 0.875rem;
}

Or use the remove-button plugin alongside tags for a polished look:

<select
  data-dot-select
  data-create-items="true"
  data-plugins="tags,remove-button"
  multiple
  data-placeholder="Add and remove tags..."
>
  <option value="bug" selected>Bug</option>
  <option value="feature" selected>Feature</option>
</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-create-items="true"
      data-plugins="tags,remove-button"
      multiple
      data-placeholder="Add and remove tags..."
    >
      <option value="bug" selected>Bug</option>
      <option value="feature" selected>Feature</option>
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-create-items="true"
    data-plugins="tags,remove-button"
    multiple
    data-placeholder="Add and remove tags..."
  >
    <option value="bug" selected>Bug</option>
    <option value="feature" selected>Feature</option>
  </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>

Tagging Configuration

Attribute	Description	Default
data-create-items	Allow creating new options	false
data-create-items-text	Text for the "Add" prompt. Use {@term} for the typed value	Add "{@term}"
data-create-items-pattern	Regex pattern to validate new values	—
data-plugins="tags"	Enable the tags plugin for comma-separated input	—
data-tags-separator	Separator character for the tags plugin	,

Complete Example

A full tagging setup with remove buttons, paste support, and existing options:

<label for="skills">Skills</label>
<select
  id="skills"
  name="skills[]"
  data-dot-select
  data-searchable="true"
  data-create-items="true"
  data-create-items-text="Add skill: {@term}"
  data-create-items-pattern="^[a-zA-Z0-9\s._-]+$"
  data-plugins="tags,remove-button"
  data-placeholder="Type skills separated by commas..."
  multiple
>
  <option value="javascript" selected>JavaScript</option>
  <option value="python" selected>Python</option>
  <option value="html">HTML</option>
  <option value="css">CSS</option>
  <option value="sql">SQL</option>
  <option value="docker">Docker</option>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('#skills')

// 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 (
    <label for="skills">Skills</label>
    <select
      id="skills"
      name="skills[]"
      data-dot-select
      data-searchable="true"
      data-create-items="true"
      data-create-items-text="Add skill: {@term}"
      data-create-items-pattern="^[a-zA-Z0-9\s._-]+$"
      data-plugins="tags,remove-button"
      data-placeholder="Type skills separated by commas..."
      multiple
    >
      <option value="javascript" selected>JavaScript</option>
      <option value="python" selected>Python</option>
      <option value="html">HTML</option>
      <option value="css">CSS</option>
      <option value="sql">SQL</option>
      <option value="docker">Docker</option>
    </select>
  )
}

<template>
  <label for="skills">Skills</label>
  <select
    id="skills"
    name="skills[]"
    data-dot-select
    data-searchable="true"
    data-create-items="true"
    data-create-items-text="Add skill: {@term}"
    data-create-items-pattern="^[a-zA-Z0-9\s._-]+$"
    data-plugins="tags,remove-button"
    data-placeholder="Type skills separated by commas..."
    multiple
  >
    <option value="javascript" selected>JavaScript</option>
    <option value="python" selected>Python</option>
    <option value="html">HTML</option>
    <option value="css">CSS</option>
    <option value="sql">SQL</option>
    <option value="docker">Docker</option>
  </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>