API Reference

Complete documentation for segmented-input. For interactive examples of every preset, see the live demos.

Built-in presets

Usage

import { SegmentedInput } from 'segmented-input/src/segmented-input.js'
import * as presets from 'segmented-input/src/presets.js'

new SegmentedInput(el, presets.ipv4)
new SegmentedInput(el, presets.rgba)
new SegmentedInput(el, presets.duration)
// … any key from the table above

Custom format

Supply a segments array (one entry per segment), a format function (array → display string), and a parse function (display string → array):

new SegmentedInput(el, {
  segments: [
    { value: '125', min: 0, max: 255, step: 1   },   // r
    { value: '125', min: 0, max: 255, step: 1   },   // g
    { value: '125', min: 0, max: 255, step: 1   },   // b
    { value: '0.5', min: 0, max: 1,   step: 0.1 },   // a
  ],
  format: (v) => `rgba(${v[0]}, ${v[1]}, ${v[2]}, ${v[3]})`,
  parse: (s) => {
    const m = s.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/)
    return m ? [m[1], m[2], m[3], m[4] ?? '1'] : ['0', '0', '0', '1']
  },
})

Segment properties

Action segments

Action segments are non-editable "button" segments embedded in the input value — useful for "clear", "today", geolocation, or toggle icons. The library adds the si-action-active class to the input when an action segment is focused, letting you style the amber selection:

new SegmentedInput(el, {
  segments: [
    { value: '2024', placeholder: 'yyyy', min: 1, max: 9999, step: 1 },
    { value: '06',   placeholder: 'mm',   min: 1, max: 12,   step: 1 },
    { value: '15',   placeholder: 'dd',   min: 1, max: 31,   step: 1 },
    { value: '⏱︎',    placeholder: '⏱︎', type: 'action', onClick(instance) {
        const t = new Date()
        instance.setSegmentValue(0, `${t.getFullYear()}`)
        instance.setSegmentValue(1, `${t.getMonth() + 1)}`.padStart(2, '0'))
        instance.setSegmentValue(2, `${t.getDate()}`.padStart(2, '0'))
      },
    },
  ],
  format: (v) => `${v[0]}-${v[1]}-${v[2]} ${v[3]}`,
  parse:  (s) => { /* … */ },
})

/* Highlight the action segment in amber when focused */
input.si-action-active::selection {
  background: #f0ad4e;
  color: #000;
}

Constructor

const instance = new SegmentedInput(inputElement, options)

Instance methods

Reading the value

For inputs without action segments, read input.value as normal. For inputs with action segments (icons embedded in the value string), use the instance's value getter, which strips the icon segments:

const inst = new SegmentedInput(input, optionsWithActionSegments)

// ✅ Clean value, icons stripped
console.log(inst.value)

// ⚠️  Raw value — includes icon characters when action segments are present
console.log(input.value)

Instance events

The underlying <input> element dispatches these custom events:

const inst = new SegmentedInput(input, presets.date)

inst.addEventListener('segmentfocus', evt => {
  console.log('focused segment', evt.detail.index)
})
inst.addEventListener('segmentchange', evt => {
  console.log('segment', evt.detail.index, 'changed to', evt.detail.value)
})

Low-level helpers

These utilities are exported separately for advanced use cases:

import {
  getSegmentRanges,
  getCursorSegment,
  highlightSegment,
} from 'segmented-input'