Download the PHP package webcito/jquery-select-suggest without Composer

jquery-selectSuggest

Create a Bootstrap-powered jQuery dropdown for server-side suggestions (typeahead with selectable items). Works with a simple HTTP endpoint returning JSON.

Table of contents

• Overview
• Stack and requirements
• Installation (CDN and self-hosted)
• Installation via Composer
• Usage
  • html
  • javascript
• Options
• Methods
• Events
• Required response for suggestion
• Backend example
• Examples for multiple display
• Scripts
• Environment variables
• Run the demo locally
• Tests
• Project structure
• License
• Changelog

Overview

jquery-selectSuggest enhances a text input to fetch and display suggestions from your backend and lets users pick one or many items. It ships as a single jQuery plugin with no custom CSS — it reuses Bootstrap utilities and components.

Stack and requirements

• Language: JavaScript (jQuery plugin)
• UI framework: Bootstrap
  • Recommended: Bootstrap 5.x
  • Note: Bootstrap 4 may work, but is not actively verified here. TODO: confirm Bootstrap 4 compatibility.
• jQuery: developed and tested with 3.6.x (earlier versions not verified)
• Optional: Bootstrap Icons (for the small remove "x" inside the widget)
• Demo backend: PHP 8.0+ (only required for the example in demo/)

Installation (CDN and self-hosted)

No additional CSS is required; Bootstrap classes are used.

CDN example (Bootstrap 5 + jQuery + optional Bootstrap Icons):

CDN for the plugin itself:

• jsDelivr (GitHub):

  Note: If your release tag is named differently (e.g. v1.1.7), adjust the @1.1.7 segment accordingly.

• When published to npm, you can also use:
  • jsDelivr (npm): https://cdn.jsdelivr.net/npm/@webcito/[email protected]/dist/jquery.bsSelectSuggest.min.js
  • unpkg: https://unpkg.com/@webcito/[email protected]/dist/jquery.bsSelectSuggest.min.js

Self-hosted (no CDN):

Locales can be loaded before plugin initialization. A locale file sets window.bsSuggestTranslations; the plugin merges defaults first, then the loaded locale, then manually provided translations.

Included European locales: be-BY, bg-BG, bs-BA, ca-ES, cs-CZ, cy-GB, da-DK, de-DE, el-GR, en-GB, es-ES, et-EE, eu-ES, fi-FI, fr-FR, ga-IE, gl-ES, hr-HR, hu-HU, is-IS, it-IT, lb-LU, lt-LT, lv-LV, mk-MK, mt-MT, nb-NO, nl-NL, pl-PL, pt-PT, ro-RO, ru-RU, sk-SK, sl-SI, sq-AL, sr-RS, sv-SE, tr-TR, uk-UA.

Installation via Composer

Composer is not required to use the plugin in the browser. The JavaScript you need lives in dist/. In this repository, Composer is primarily used for the PHP demo to fetch Bootstrap and jQuery into vendor/ (see “Run the demo locally”).

If you still want to manage this plugin in a PHP project via Composer, you have two options:

1) Packagist (when available)

• TODO: Publish the package to Packagist.
• Expected package name (per composer.json): webcito/jquery-select-suggest.

• Once published, install with:

• After installation, copy or symlink the browser assets from vendor/webcito/jquery-select-suggest/dist/ into your public web directory and include them in your HTML:

2) VCS repository (use this Git repo directly)

• Add a VCS repository entry to your project’s composer.json and require the package by name:

Replace https://github.com/REPO_OWNER/jquery-bs-suggest with the actual Git repository URL of this project.

• Then run:

• As with Packagist, include the built file from vendor/webcito/jquery-select-suggest/dist/ in your HTML.

Notes

• Composer does not automatically wire front-end assets. You must publish/copy/symlink the files in dist/ to a web-accessible location (or reference them directly from your server’s vendor path if appropriate).
• If you do not want Composer at all, simply copy dist/jquery.bsSelectSuggest.min.js into your project and include it as shown in Installation above.

Usage

html

Place the input field where you want the dropdown to appear.

javascript

Quick start example (full page):

Options

Minimal, clear options grouped by purpose.

Notes:

• Locale files in dist/locale/ provide ready-to-use translations. Load one locale before calling .suggest() to use it as the default UI text set. Explicit options.translations values always win.
• Legacy names are still accepted and mapped internally to the new schema:
  • emptyText/btnEmptyText → translations.placeholder
  • searchPlaceholderText → translations.search
  • waitingForTypingText → translations.waiting
  • typingText → translations.typing
  • loadingText → translations.loading
  • headerClearText → translations.clear
  • headerCloseText → translations.close
• In multiple: true mode, the hidden input value is an array. For form submissions, use a field name with brackets, e.g. name="country_id[]" to receive an array server‑side.

Preselection with selected:

• If selected is defined and not null/empty, the plugin will immediately resolve those ids via the backend and set the selection on init (no change event is fired for this initial hydrate).
• Single select: pass a scalar (string/number). Example: selected: 1.
• Multiple select: pass an array of ids (strings/numbers). Example: selected: [1, 3].

Rendering model:

• Suggestion list items use formatItem(item) (or the server‑provided formatted HTML when present) to render rich content.
• Button content:
  • Single select (multiple: false): renders rich HTML too. Preference order: item.formatted (when provided) → options.formatItem(item) (when provided) → the built‑in formatItem(item). No inline remove control in single mode.
  • Multiple select (multiple: true): shows neutral, border‑only chips for each selected item, with an inline remove control per item. Chips are text‑only; they do not use formatItem.
• The built‑in default formatItem renders a modern, clean chip/tile with optional subtext (using only Bootstrap 5 utility classes). Override formatItem to control the suggestion list appearance; in single mode this will also affect the button when no formatted field is provided by the server.

Styling and theme compatibility:

• The dropdown uses only Bootstrap utility classes; no custom CSS and no styling options are required. It respects light/dark themes and different button variants.
• Selected items in the dropdown menu no longer rely on colored backgrounds; instead, a trailing icon indicates state (icons.checked/icons.unchecked).

Multiple button layout:

• showMultipleAsList (boolean): Controls how selected items are laid out inside the button when multiple: true.
  • true (default): vertical stack (d-flex flex-column align-items-start).
  • false: floating/wrapping layout (d-flex flex-wrap align-items-center gap-1). The plugin also relaxes some block utilities (e.g. converts w-100 to w-auto) for a tighter inline look.

Dropdown header actions (to avoid ambiguous "x"):

• The header shows Clear and Close actions by default (icons only). You can customize labels via translations.clear and translations.close, and toggle labels via showHeaderActionText.
  • Behavior:
  • Clear resets only the current selection and keeps the current search and results list intact (dropdown stays open).
  • Close hides the dropdown.
  • Keyboard: Enter/Space on these buttons trigger the respective action.
  • Backward compatibility: the previous .js-webcito-reset control maps to Clear.

Removal from selection (multiple mode):

• Each selected item shown in the button includes a small remove control ("x"). The inline remove is only present in multiple: true and is hidden when the widget is disabled.
• Clicking it removes that item from the selection, updates the hidden input array, re-renders the button, syncs the active state in the dropdown, and triggers change.bs.suggest with ([ids], [items]).
• For best visuals, include Bootstrap Icons:

Deprecated (backward compatibility):

• multipleBadgeClass, formatBadge are deprecated and ignored — use formatItem.
• Removed/cleaned options: menuClass, density, menuMaxHeight, showCheckmark, checkIconHtml, highlightQuery, headerClass, searchInputClass, itemClass, activeItemClass, headerActionMode.
  • If debug: true, the plugin logs a warning when any of these are provided. Use icons for icon customization, translations for texts, and formatItem for list content.

Methods

Events

Required response for suggestion

The parameters q and limit are sent to the server via GET. q is in this case the search string and limit the maximum number of records to be determined. As response the plugin expects an array with items and the total number of records.
An item consists of the attributes id and text. Optionally you can provide:

• subtext (string) — a secondary line that the default renderer shows smaller below the main text (suggestion list only).
• formatted (string, HTML) — if present and non-empty, the plugin will render this HTML directly in the suggestion list, bypassing formatItem. In single select mode the button also prefers formatted; in multiple mode the button uses text‑only chips and ignores formatted.

When the method val is called, only the parameter value is sent to the server.
For single select the server should return a single item object.
For multiple select the server will send value[] as an array of IDs (jQuery serializes arrays like this) and expects an array in items. The optional fields subtext and formatted are supported here as well — if formatted is provided, it is used directly for the suggestion list. In single select mode, the button also prefers formatted/formatItem; in multiple mode the button uses text‑only chips.

backend example

A complete example can be found in the demo folder.

Examples for multiple display

Using modern chips/tiles (default rendering):

Using custom layout via formatItem (applies to the suggestion list and also to the single‑select button when no formatted is provided by the server):

Scripts

• This repository ships prebuilt files in dist/.
• No build step or package.json scripts are provided. TODO: add a build pipeline if source files are added in the future.

Package manager notes:

• The repo contains a composer.json used only for the PHP demo to fetch Bootstrap and jQuery assets under vendor/. It is NOT required to use the plugin in a browser project.

Environment variables

• None required by the plugin.
• The PHP demo in demo/ does not use environment variables.

Run the demo locally

There are two ways to try the demo in demo/:

1) Use the included Composer setup (fetches Bootstrap and jQuery into vendor/ as referenced by the demo HTML):

2) Or open the demo with CDN assets by modifying the <link>/<script> tags in demo/index.html to use the CDN URLs shown in the Installation section.

Project structure

• dist/jquery.bsSelectSuggest.js — unminified plugin
• dist/jquery.bsSelectSuggest.min.js — minified plugin
• dist/locale/ — locale files and minified locale builds
• demo/ — HTML + PHP demo and sample data
• CHANGELOG.md — changes per version
• LICENSE — MIT license
• composer.json — optional PHP dependencies for the demo; not required for browser use

Tests

• No automated tests are included. TODO: add basic integration tests (e.g., Cypress) and unit tests for client logic if a build system is introduced.

License

This project is licensed under the MIT License — see LICENSE for details.

Changelog

See CHANGELOG.md for a detailed list of changes. Current version: 1.1.7 (2026-05-07).

Support this project

If this project helps you, feel free to support its development:

☕ Buy me a coffee via PayPal