Comprehensive configuration system supporting both JavaScript options and HTML data attributes for customizing selectpicker behavior and appearance.
Options controlling the visual display and text formatting of the selectpicker.
interface DisplayOptions {
/** Text shown when no options are selected */
noneSelectedText?: string; // default: 'Nothing selected'
/** Text shown when search yields no results (supports {0} placeholder) */
noneResultsText?: string; // default: 'No results matched {0}'
/** Custom title for the selectpicker button */
title?: string | null; // default: null
/** Format for displaying selected items */
selectedTextFormat?: 'values' | 'count' | 'static'; // default: 'values'
/** Separator string for multiple selected values */
multipleSeparator?: string; // default: ', '
/** Whether to show option content/HTML */
showContent?: boolean; // default: true
/** Whether to show option icons */
showIcon?: boolean; // default: true
/** Whether to show option subtext */
showSubtext?: boolean; // default: false
/** Whether to show checkmarks for selected options */
showTick?: boolean; // default: false
}Usage Examples:
// Custom display configuration
$('#mySelect').selectpicker({
noneSelectedText: 'Choose an option...',
noneResultsText: 'No matches for "{0}"',
selectedTextFormat: 'count',
multipleSeparator: ' | ',
showSubtext: true,
showTick: true
});
// HTML data attributes<select class="selectpicker"
data-none-selected-text="Pick something..."
data-selected-text-format="count"
data-show-subtext="true"
data-show-tick="true">
<option data-subtext="Popular choice">Option 1</option>
<option data-subtext="Recommended">Option 2</option>
</select>Configuration for selection limits and related text formatting.
interface SelectionOptions {
/** Maximum number of selectable options (false for unlimited) */
maxOptions?: number | false; // default: false
/** Text for "Select All" button */
selectAllText?: string; // default: 'Select All'
/** Text for "Deselect All" button */
deselectAllText?: string; // default: 'Deselect All'
/** Text for done button in mobile mode */
doneButtonText?: string; // default: 'Close'
/** Function to format count text when selectedTextFormat is 'count' */
countSelectedText?: (numSelected: number, numTotal: number) => string;
/** Function to format max options reached text */
maxOptionsText?: (numAll: number, numGroup: number) => string[];
}Usage Examples:
// Selection limits configuration
$('#multiSelect').selectpicker({
maxOptions: 3,
selectAllText: 'Choose All',
deselectAllText: 'Clear All',
countSelectedText: function(numSelected, numTotal) {
return `${numSelected} of ${numTotal} selected`;
},
maxOptionsText: function(numAll, numGroup) {
return [
`Maximum ${numAll} selections allowed`,
`Group limit: ${numGroup} items`
];
}
});
// HTML data attributes<select class="selectpicker" multiple
data-max-options="5"
data-select-all-text="Pick All"
data-deselect-all-text="Clear Selection">
<optgroup label="Group 1">
<option>Option 1</option>
<option>Option 2</option>
</optgroup>
</select>Options for configuring the live search functionality.
interface SearchOptions {
/** Enable live search functionality */
liveSearch?: boolean; // default: false
/** Placeholder text for search input */
liveSearchPlaceholder?: string | null; // default: null
/** Enable search text normalization (remove accents, etc.) */
liveSearchNormalize?: boolean; // default: false
/** Search matching style */
liveSearchStyle?: 'contains' | 'startsWith'; // default: 'contains'
}Usage Examples:
// Search configuration
$('#searchableSelect').selectpicker({
liveSearch: true,
liveSearchPlaceholder: 'Type to search...',
liveSearchNormalize: true,
liveSearchStyle: 'startsWith'
});
// HTML data attributes<select class="selectpicker"
data-live-search="true"
data-live-search-placeholder="Search options..."
data-live-search-normalize="true"
data-live-search-style="startsWith">
<option>Apple</option>
<option>Banana</option>
<option>Cherry</option>
</select>Options controlling the size, positioning, and layout of the selectpicker dropdown.
interface LayoutOptions {
/** Dropdown size ('auto', number of visible options, or false for full height) */
size?: 'auto' | number | false; // default: 'auto'
/** Button width (CSS width value or false for auto) */
width?: string | boolean; // default: false
/** Container selector for dropdown positioning */
container?: string | boolean; // default: false
/** Automatically detect when to show dropdown upward */
dropupAuto?: boolean; // default: true
/** Align dropdown menu to the right */
dropdownAlignRight?: boolean; // default: false
/** Window padding for positioning calculations */
windowPadding?: number; // default: 0
/** Virtual scrolling threshold (number of options) */
virtualScroll?: number | boolean; // default: 600
}Usage Examples:
// Layout configuration
$('#layoutSelect').selectpicker({
size: 5,
width: '300px',
container: 'body',
dropupAuto: false,
dropdownAlignRight: true,
windowPadding: 10,
virtualScroll: 100
});
// HTML data attributes<select class="selectpicker"
data-size="8"
data-width="100%"
data-container="body"
data-dropup-auto="false"
data-dropdown-align-right="true">
<option>Long option text that might overflow</option>
<option>Another option</option>
</select>Options for customizing the visual appearance and CSS classes.
interface StyleOptions {
/** Button style CSS class */
style?: string; // default: 'btn-default' (Bootstrap 3) or 'btn-light' (Bootstrap 4)
/** Base button CSS class */
styleBase?: string; // default: 'btn'
/** Icon base CSS class */
iconBase?: string; // default: 'glyphicon' (Bootstrap 3) or '' (Bootstrap 4)
/** Checkmark icon CSS class */
tickIcon?: string; // default: 'glyphicon-ok' (Bootstrap 3) or 'bs-ok-default' (Bootstrap 4)
/** Custom HTML templates */
template?: {
caret?: string; // default: '<span class="caret"></span>'
};
}Usage Examples:
// Styling configuration
$('#styledSelect').selectpicker({
style: 'btn-primary',
styleBase: 'btn',
iconBase: 'fa',
tickIcon: 'fa-check',
template: {
caret: '<i class="fa fa-chevron-down"></i>'
}
});
// HTML data attributes<select class="selectpicker"
data-style="btn-success"
data-icon-base="fa"
data-tick-icon="fa-check">
<option data-icon="fa fa-home">Home</option>
<option data-icon="fa fa-user">Profile</option>
</select>Options controlling the interactive behavior of the selectpicker.
interface BehaviorOptions {
/** Enable mobile-specific behavior */
mobile?: boolean; // default: false
/** Allow selection on Tab key press */
selectOnTab?: boolean; // default: false
/** Hide disabled options from dropdown */
hideDisabled?: boolean; // default: false
/** Show actions box with Select All/Deselect All buttons */
actionsBox?: boolean; // default: false
/** Show done button in mobile mode */
doneButton?: boolean; // default: false
/** Header text for dropdown */
header?: string | boolean; // default: false
/** Display mode flag */
display?: boolean; // default: false
}Usage Examples:
// Behavior configuration
$('#behaviorSelect').selectpicker({
mobile: true,
selectOnTab: true,
hideDisabled: true,
actionsBox: true,
doneButton: true,
header: 'Choose Options'
});
// HTML data attributes<select class="selectpicker" multiple
data-actions-box="true"
data-header="Select your preferences"
data-hide-disabled="true"
data-select-on-tab="true">
<option>Available option</option>
<option disabled>Disabled option</option>
</select>Options for HTML sanitization and security features.
interface SecurityOptions {
/** Enable HTML sanitization */
sanitize?: boolean; // default: true
/** Custom sanitization function */
sanitizeFn?: ((unsafeElements: Element[]) => void) | null; // default: null
/** HTML whitelist for sanitization */
whiteList?: { [tagName: string]: string[] }; // default: DefaultWhitelist
}Usage Examples:
// Security configuration
$('#secureSelect').selectpicker({
sanitize: true,
sanitizeFn: function(unsafeElements) {
// Custom sanitization logic
unsafeElements.forEach(element => {
// Remove potentially dangerous attributes
element.removeAttribute('onclick');
element.removeAttribute('onload');
});
},
whiteList: {
'b': [],
'i': [],
'em': [],
'strong': [],
'span': ['class']
}
});
// Disable sanitization (not recommended)
$('#unsafeSelect').selectpicker({
sanitize: false
});Options for customizing the HTML templates used by selectpicker.
interface TemplateOptions {
/** Template configuration object */
template?: {
/** HTML template for the dropdown caret */
caret?: string; // default: '<span class="caret"></span>'
};
}Usage Examples:
// Template configuration
$('#templatedSelect').selectpicker({
template: {
caret: '<i class="fas fa-chevron-down"></i>'
}
});
// Custom caret with Font Awesome
$('#faSelect').selectpicker({
template: {
caret: '<i class="fa fa-angle-down" aria-hidden="true"></i>'
}
});
// Bootstrap 4 style caret
$('#bs4Select').selectpicker({
template: {
caret: '<span class="caret"></span>'
}
});Complete mapping of JavaScript options to HTML data attributes.
<!-- Display options -->
<select data-none-selected-text="..."
data-none-results-text="..."
data-title="..."
data-selected-text-format="..."
data-multiple-separator="..."
data-show-content="true|false"
data-show-icon="true|false"
data-show-subtext="true|false"
data-show-tick="true|false">
<!-- Selection options -->
<select data-max-options="number"
data-select-all-text="..."
data-deselect-all-text="..."
data-done-button-text="...">
<!-- Search options -->
<select data-live-search="true|false"
data-live-search-placeholder="..."
data-live-search-normalize="true|false"
data-live-search-style="contains|startsWith">
<!-- Layout options -->
<select data-size="auto|number"
data-width="..."
data-container="..."
data-dropup-auto="true|false"
data-dropdown-align-right="true|false"
data-virtual-scroll="number">
<!-- Style options -->
<select data-style="..."
data-icon-base="..."
data-tick-icon="...">
<!-- Behavior options -->
<select data-mobile="true|false"
data-select-on-tab="true|false"
data-hide-disabled="true|false"
data-actions-box="true|false"
data-done-button="true|false"
data-header="...">
<!-- Security options -->
<select data-sanitize="true|false">