@smilodon/solid

SolidJS adapter for Smilodon's core custom-element select engine.

This package gives Solid applications a native-feeling wrapper around the shared enhanced-select runtime while preserving the same capabilities available in the other adapters: grouped data, multi-select, search, virtualization, clear control, diagnostics, and limitation-policy APIs.

📖 Documentation

Live documentation & interactive examples: navidrezadoost.github.io/Smilodon

Framework integration (Vue 3, Nuxt 4, React, SSR, Vite): docs/FRAMEWORK-INTEGRATION.md

For comprehensive documentation covering installation, setup, controlled and uncontrolled usage, renderers, performance, SSR posture, diagnostics, and troubleshooting:

👉 Complete SolidJS Guide 👈

The complete guide includes:

• ✅ Solid-specific setup and custom-element lifecycle guidance
• ✅ Simple, medium, and advanced usage patterns
• ✅ Full prop and callback coverage
• ✅ JSX renderer and DOM renderer strategies
• ✅ Performance and large-list guidance
• ✅ Diagnostics, limitations, and troubleshooting

Installation

npm install @smilodon/solid @smilodon/core solid-js

What this adapter adds

• Solid-friendly prop API for controlled and uncontrolled usage
• Callback ref handle exposing open(), close(), clear(), setItems(), and diagnostics helpers
• Two renderer paths:
  • customRenderer for JSX content rendered through Solid
  • optionRenderer for direct HTMLElement output when you want full DOM control
• Automatic conversion of flat items with a group field into grouped data
• Safe custom-element upgrade handling before imperative syncing begins

Quick start

import { render } from 'solid-js/web'
import { createSignal } from 'solid-js'
import { Select } from '@smilodon/solid'

function App() {
  const [value, setValue] = createSignal<string | number>('')

  return (
    <Select
      items={[
        { value: 'apple', label: 'Apple' },
        { value: 'banana', label: 'Banana' },
        { value: 'cherry', label: 'Cherry' },
      ]}
      value={value()}
      onChange={(next) => setValue(next as string)}
      searchable
      clearable
      placeholder="Pick a fruit"
    />
  )
}

render(() => <App />, document.getElementById('app')!)

Clear control visibility

With clearable, an empty field reserves no space for the clear action. The button and its input/arrow spacing appear only when a selected value or enabled search query can be cleared, then disappear after both targets are empty. This behavior covers single and multi-select as well as LTR and RTL layouts.

<Select
  items={items}
  value={value()}
  onChange={setValue}
  searchable
  clearable
  clearSelectionOnClear
  clearSearchOnClear
  onClear={(detail) => console.log(detail)}
/>

To keep a disabled clear action visible while empty, pass config={{ clearControl: { hideWhenEmpty: false } }}. Style through ::part(clear-button), ::part(clear-icon), and --select-clear-*; avoid permanent input padding.

Controlled and uncontrolled modes

Controlled

Use value plus onChange when your store or signal owns the selection.

const [value, setValue] = createSignal<Array<string | number>>([])

<Select
  items={items}
  value={value()}
  onChange={(next) => setValue(next as Array<string | number>)}
  multiple
  searchable
/>

Uncontrolled

Use defaultValue when the component should manage its own internal state after initial mount.

<Select
  items={items}
  defaultValue="banana"
  searchable
/>

Grouped data

You can supply either groupedItems directly or pass flat items with a group property.

<Select
  items={[
    { value: 'tehran', label: 'Tehran', group: 'Asia' },
    { value: 'tokyo', label: 'Tokyo', group: 'Asia' },
    { value: 'berlin', label: 'Berlin', group: 'Europe' },
  ]}
  searchable
/>

If you already have grouped data, pass groupedItems and optionally render headers with groupHeaderRenderer.

Direction and option-state controls

<Select
  items={items}
  direction="rtl"
  removeButtonIcon="−"
  disabledOptionBehavior={{ hoverable: true, focusable: true, selectable: false }}
  showSelectedIndicator={false}
/>

• direction switches the instance between ltr and rtl
• removeButtonIcon replaces the chip remove icon with text or inline SVG markup
• disabledOptionBehavior controls whether dimmed options can still be hovered, focused, or selected
• showSelectedIndicator hides or shows the selected side indicator without custom pseudo-element rules

Core config parity and global defaults

The Solid adapter now exposes the shared core configuration model through both convenience props and a full config prop.

Convenience props

Use these adapter props for the most common advanced core features:

• selectionConfig
• multiSelectDisplay
• scrollToSelected
• styles
• config

import { Select } from '@smilodon/solid'
import { createSignal } from 'solid-js'

function HorizontalChipExample() {
  const [value, setValue] = createSignal<Array<string | number>>(['react', 'solid'])

  return (
    <Select
      items={[
        { value: 'react', label: 'React' },
        { value: 'vue', label: 'Vue' },
        { value: 'svelte', label: 'Svelte' },
        { value: 'solid', label: 'Solid' },
      ]}
      value={value()}
      onChange={(next) => setValue(next as Array<string | number>)}
      multiple
      searchable
      multiSelectDisplay={{
        mode: 'horizontal',
        maxHeight: '56px',
        overflowX: 'auto',
        overflowY: 'hidden',
        dragScroll: true,
      }}
      selectionConfig={{
        closeOnSelect: false,
        toggleOnTriggerClick: true,
      }}
      styles={{
        badgeRemoveIcon: {
          color: '#dc2626',
          transform: 'scale(1.1)',
        },
      }}
      removeButtonIcon="−"
    />
  )
}

Full config passthrough

<Select
  items={items}
  multiple
  config={{
    dropdownPlacement: { mode: 'auto' },
    scrollToSelected: {
      enabled: true,
      multiSelectTarget: 'last',
    },
    multiSelectDisplay: {
      mode: 'vertical',
      maxHeight: '120px',
    },
    selection: {
      allowDeselect: true,
      closeOnSelect: false,
    },
    styles: {
      badge: {
        background: '#eff6ff',
        border: '1px solid #bfdbfe',
        color: '#1d4ed8',
      },
      badgeRemoveIcon: {
        color: '#1d4ed8',
      },
    },
  }}
/>

Global defaults from @smilodon/solid

import { configureSelect } from '@smilodon/solid'

configureSelect({
  searchable: true,
  clearControl: {
    enabled: true,
    clearSelection: true,
    clearSearch: true,
  },
  selection: {
    showSelectedIndicator: false,
    removeButtonIcon: '×',
  },
})

Renderers

customRenderer

Use customRenderer when you want JSX-based option content driven by Solid rendering.

<Select
  items={items}
  customRenderer={(item) => (
    <div style={{ display: 'flex', 'justify-content': 'space-between' }}>
      <span>{item.label}</span>
      <strong>{String(item.value)}</strong>
    </div>
  )}
/>

optionRenderer

Use optionRenderer when you want to return an HTMLElement directly.

<Select
  items={items}
  optionRenderer={(item, index, helpers) => {
    const el = document.createElement('div')
    el.textContent = `${index + 1}. ${item.label}`
    el.onclick = () => helpers?.onSelect(item, index)
    return el
  }}
/>

Imperative handle

The Solid adapter uses a callback ref rather than React-style useRef forwarding.

let api

<Select
  items={items}
  ref={(handle) => {
    api = handle
  }}
/>

<button onClick={() => api?.open()}>Open</button>
<button onClick={() => api?.clear()}>Clear</button>

Available handle methods include:

• focus()
• open()
• close()
• getSelectedItems()
• getSelectedValues()
• setItems()
• setGroupedItems()
• clear()
• clearSearch()
• updateConfig()
• setError()
• clearError()
• setRequired()
• validate()
• getCapabilities()
• getKnownLimitations()
• getTrackingSnapshot()
• clearTracking()
• setLimitationPolicies()

Example:

let api

<Select
  items={items}
  ref={(handle) => {
    api = handle
  }}
/>

<button onClick={() => api?.clearSearch()}>Clear Search</button>
<button onClick={() => api?.updateConfig({ selection: { showSelectedIndicator: false } })}>
  Hide Indicator
</button>
<button onClick={() => api?.setError('Selection required')}>Set Error</button>
<button onClick={() => console.log(api?.validate())}>Validate</button>

Diagnostics and limitation policies

Like the audited web adapters, Solid can emit diagnostic payloads and expose runtime capability reports.

<Select
  items={items}
  trackingEnabled
  emitDiagnostics
  onDiagnostic={(detail) => console.log(detail)}
/>

Use limitationPolicies or setLimitationPolicies() when you want to suppress or tighten runtime behavior around known limitations.

Styling

The Solid adapter does not invent a separate styling model. Use the shared token surface and ::part() hooks documented in:

• ../../docs/STYLING.md
• ../../docs/STYLING-TOKENS.md

Common hooks:

• --select-input-*
• --select-badge-*
• --select-dropdown-*
• --select-option-*
• ::part(button)
• ::part(listbox)
• ::part(option)
• ::part(chip)
• ::part(clear-button)

Performance guidance

• Leave virtualized enabled for large lists.
• Provide stable items references when possible.
• Use optionRenderer carefully for very large datasets; heavier DOM per row increases layout cost.
• Prefer flat text or lightweight JSX for the fastest scrolling path.

Related docs

• Root overview
• Core styling guide
• Known limitations
• Performance guide