# Bootstrap — User Guide
## 1. Quick Start
Bootstrap is the most popular HTML, CSS, and JavaScript front-end framework for building responsive, mobile-first websites and web applications. It provides a comprehensive design system with a 12-column grid, dozens of pre-built components, 12 interactive JavaScript plugins, and a powerful Sass-based customization layer — all in under 30 kB of CSS and 24 kB of JS (gzipped).
### Key Features
- **Responsive grid system** with 6 breakpoints (xs through xxl) and flexbox-based layout
- **12 JavaScript plugins** — Alert, Button, Carousel, Collapse, Dropdown, Modal, Offcanvas, Popover, ScrollSpy, Tab, Toast, Tooltip — all usable via data attributes or JavaScript API
- **Sass-first customization** — override 700+ variables, use mixins and the utilities API to generate only the CSS you need
- **Color modes** — built-in light and dark theme support with automatic OS preference detection
- **RTL support** — right-to-left layouts generated automatically via RTLCSS
- **No jQuery required** — pure vanilla JavaScript; jQuery detected optionally via `window.jQuery` but never mandatory
- **Peer dependency** — only `@popperjs/core` ^2.11.8, and only for Dropdown, Popover, and Tooltip
### CDN Quickstart
Create an `index.html` file with this content to start using Bootstrap immediately:
```html
My Bootstrap Page
Hello, Bootstrap 5.3.8!
You're up and running.
It Works!
Bootstrap is loaded and interactive components are working.
```
Open this file in a browser. You should see a heading, a lead paragraph, and a blue "Launch Demo Modal" button. Clicking the button opens a centered modal dialog — confirming both CSS and JS are loaded correctly.
> [!TIP]
> The **bundle** version (`bootstrap.bundle.min.js`) includes Popper.js, so you get Dropdowns, Popovers, and Tooltips without an extra script tag. Use this unless you have a specific reason to load Popper separately.
**What to try next:** Jump to [Core Usage](#4-core-usage) for the grid system and components, or [Common Tasks](#5-common-tasks) for ready-to-use recipes like responsive navbars and dark mode toggles.
---
## 2. Installation
### Requirements
| Requirement | Minimum | Notes |
|---|---|---|
| Browser | Chrome, Firefox, Edge, Safari (latest 2 major versions) | IE is not supported |
| Node.js | 14+ | Only needed for npm/build workflows |
| Popper.js | `@popperjs/core` ^2.11.8 | Only for Dropdown, Popover, Tooltip — included in the bundle build |
| Sass compiler | Dart Sass 1.33+ | Only if customizing via SCSS |
### Method 1: CDN (No Build Tools)
Add these two tags to your HTML `` and before ``:
```html
```
For **RTL layouts**, use the RTL CSS instead:
```html
```
If you need **separate Popper** (instead of the bundle):
```html
```
### Method 2: npm
```bash
npm install bootstrap@5.3.8
```
Expected output:
```
added 2 packages in 3s
```
This installs Bootstrap and its peer dependency `@popperjs/core`. Import in your JavaScript:
```javascript
// ES module import (recommended for bundlers)
import * as bootstrap from 'bootstrap';
// Or import individual plugins
import { Modal, Tooltip } from 'bootstrap';
```
Import the CSS in your bundler entry point or Sass file:
```scss
// Option A: Import all of Bootstrap's CSS
@import "bootstrap/dist/css/bootstrap.min.css";
// Option B: Import Bootstrap's Sass source for customization
@import "bootstrap/scss/bootstrap";
```
The npm package exposes these entry points:
| Field | Path | Use Case |
|---|---|---|
| `main` | `dist/js/bootstrap.js` | CommonJS / UMD |
| `module` | `dist/js/bootstrap.esm.js` | ES modules (tree-shakeable) |
| `sass` | `scss/bootstrap.scss` | Sass source |
| `style` | `dist/css/bootstrap.css` | Pre-compiled CSS |
### Method 3: Composer (PHP)
```bash
composer require twbs/bootstrap:5.3.8
```
### Method 4: NuGet (.NET)
```powershell
Install-Package bootstrap -Version 5.3.8
```
### Method 5: Source Download
| Package | URL |
|---|---|
| Compiled CSS & JS | https://github.com/twbs/bootstrap/releases/download/v5.3.8/bootstrap-5.3.8-dist.zip |
| Source code | https://github.com/twbs/bootstrap/archive/v5.3.8.zip |
| Examples | https://github.com/twbs/bootstrap/releases/download/v5.3.8/bootstrap-5.3.8-examples.zip |
### Verification
After installation, verify Bootstrap is loaded by opening your browser's developer console and running:
```javascript
// Check CSS is loaded — should return a CSSStyleSheet object
document.querySelector('link[href*="bootstrap"]')?.sheet
// Check JS is loaded — should return "5.3.8"
bootstrap.Modal.VERSION
```
> [!IMPORTANT]
> Always include the `integrity` and `crossorigin="anonymous"` attributes when loading from CDN. Subresource Integrity (SRI) protects against compromised CDN files.
---
## 3. Configuration
### Sass Variable Customization
Bootstrap's design is driven by Sass variables. Override them **before** importing Bootstrap:
```scss
// custom.scss
// 1. Override default variables
$primary: #7952b3;
$font-family-base: 'Inter', sans-serif;
$border-radius: 0.5rem;
$enable-shadows: true;
$enable-gradients: true;
$enable-negative-margins: true;
// 2. Import Bootstrap
@import "bootstrap/scss/bootstrap";
```
Compile with Dart Sass:
```bash
sass custom.scss custom.css
```
> [!NOTE]
> You must use Dart Sass (not LibSass or Ruby Sass). If you see deprecation warnings about mixed declarations with Dart Sass 1.80.0+, this is a known upstream issue — the warnings are cosmetic and do not affect output.
### Importing Only What You Need
Reduce your CSS bundle by importing individual components:
```scss
// Required core
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/root";
// Optional components (pick what you use)
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
@import "bootstrap/scss/containers";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/buttons";
@import "bootstrap/scss/modal";
@import "bootstrap/scss/utilities";
@import "bootstrap/scss/utilities/api"; // Must be last — generates utility classes
```
### Color Modes (Light / Dark / Auto)
Bootstrap 5.3.8 supports color modes via the `data-bs-theme` attribute on `` or any container element:
```html
```
To **automatically match the OS preference**, add this script before Bootstrap's CSS loads:
```javascript
// Auto-detect and apply color mode
(() => {
const stored = localStorage.getItem('theme');
if (stored) {
document.documentElement.setAttribute('data-bs-theme', stored);
} else {
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.setAttribute('data-bs-theme', prefersDark ? 'dark' : 'light');
}
})();
```
Nest color modes for per-section theming:
```html
Light content here
```
### Theme Colors
Bootstrap defines 8 semantic theme colors used across components:
| Name | Default Hex | Usage |
|---|---|---|
| `primary` | `#0d6efd` | Buttons, links, active states |
| `secondary` | `#6c757d` | Muted actions, subtle elements |
| `success` | `#28a745` | Positive feedback, confirmations |
| `danger` | `#dc3545` | Errors, destructive actions |
| `warning` | `#ffc107` | Caution states (dark text for contrast) |
| `info` | `#17a2b8` | Informational highlights |
| `light` | `#f8f9fa` | Light backgrounds |
| `dark` | `#343a40` | Dark backgrounds, emphasis |
Override any color via Sass variables before the import (e.g., `$primary: #7952b3;`).
### RTL (Right-to-Left) Support
To enable RTL layout:
1. Set `dir="rtl"` on the `` element
2. Use the RTL CSS build instead of the default:
```html
```
If building from Sass, set `$enable-rtl: true` and compile with RTLCSS in your pipeline.
### jQuery Compatibility
Bootstrap 5.3.8 does not require jQuery. However, it detects jQuery automatically via `window.jQuery` and will use it if present. To **explicitly disable** jQuery integration even when jQuery is on the page, add a data attribute to the ``:
```html
```
For the full Sass variable reference and advanced build configuration, see the **Admin Guide**.
---
## 4. Core Usage
### Layout
#### Containers
Containers are the fundamental layout wrapper. Bootstrap provides three container types:
```html
...
...
...
...
...
...
...
```
Container max-widths by breakpoint:
| Breakpoint | Abbr. | Min-Width | `.container` Max-Width |
|---|---|---|---|
| xs | (none) | 0 px | 100% (fluid) |
| sm | `-sm` | 576 px | 540 px |
| md | `-md` | 768 px | 720 px |
| lg | `-lg` | 992 px | 960 px |
| xl | `-xl` | 1200 px | 1140 px |
| xxl | `-xxl` | 1400 px | 1320 px |
#### Grid System
Bootstrap uses a 12-column flexbox grid. Columns must be inside a `.row`, and rows must be inside a container:
```html
```
**Row columns (shorthand for equal-width layouts):**
```html
Item
Item
Item
Item
```
**Gutters:**
```html
...
...
...
...
```
**Offsetting columns:**
```html
Centered 6-column block
```
### Components (JavaScript Plugins)
All 12 JavaScript plugins can be used in two ways: via **data attributes** (no JavaScript needed) or via the **JavaScript API**. Every plugin fires namespaced events in the pattern `action.bs.component` (e.g., `show.bs.modal`, `hidden.bs.collapse`).
#### Alert
Dismissible alerts with a close button:
```html
Warning! Check your input before submitting.
```
Via JavaScript:
```javascript
const alertEl = document.querySelector('.alert');
const bsAlert = bootstrap.Alert.getOrCreateInstance(alertEl);
bsAlert.close();
```
Events: `close.bs.alert`, `closed.bs.alert`.
#### Button
Toggle active state on buttons:
```html
```
Via JavaScript:
```javascript
const btn = document.querySelector('.btn');
const bsButton = bootstrap.Button.getOrCreateInstance(btn);
bsButton.toggle();
```
#### Carousel
Image slideshow with controls and indicators:
```html
First Slide
Description here.
```
Carousel defaults:
| Option | Default | Description |
|---|---|---|
| `interval` | `5000` | Time (ms) between auto-cycling slides |
| `keyboard` | `true` | React to keyboard arrow keys |
| `pause` | `'hover'` | Pause on mouse hover (`false` to disable) |
| `ride` | `false` | Auto-play on load (`'carousel'` to enable) |
| `touch` | `true` | Support swipe on touch devices |
| `wrap` | `true` | Cycle continuously or stop at last slide |
Events: `slide.bs.carousel`, `slid.bs.carousel`.
#### Collapse
Toggle visibility of content:
```html
Toggle Content
This content is collapsible.
```
Collapse defaults:
| Option | Default | Description |
|---|---|---|
| `parent` | `null` | Selector for accordion behavior (only one open at a time) |
| `toggle` | `true` | Toggle on initialization |
Events: `show.bs.collapse`, `shown.bs.collapse`, `hide.bs.collapse`, `hidden.bs.collapse`.
#### Dropdown
Toggleable menus for navigation and actions:
```html
```
Dropdown defaults:
| Option | Default | Description |
|---|---|---|
| `autoClose` | `true` | Close behavior: `true`, `'inside'`, `'outside'`, `false` |
| `boundary` | `'clippingParents'` | Overflow constraint boundary for Popper |
| `display` | `'dynamic'` | `'dynamic'` (Popper positioning) or `'static'` |
| `offset` | `[0, 2]` | `[skidding, distance]` in pixels |
| `popperConfig` | `null` | Custom Popper.js configuration object |
| `reference` | `'toggle'` | Reference element: `'toggle'`, `'parent'`, or an HTMLElement |
> [!NOTE]
> Dropdowns require Popper.js. Use the **bundle** build (`bootstrap.bundle.min.js`) or load Popper separately before Bootstrap's JS.
Events: `show.bs.dropdown`, `shown.bs.dropdown`, `hide.bs.dropdown`, `hidden.bs.dropdown`.
#### Modal
Dialogs for confirmations, forms, and content:
```html
Modal Title
Modal content goes here.
```
Modal defaults:
| Option | Default | Description |
|---|---|---|
| `backdrop` | `true` | Show backdrop; `'static'` prevents close on backdrop click |
| `focus` | `true` | Focus the modal when opened |
| `keyboard` | `true` | Close on Escape key |
Modal sizes: `.modal-sm`, `.modal-lg`, `.modal-xl`. Fullscreen: `.modal-fullscreen` or responsive variants like `.modal-fullscreen-lg-down`.
Via JavaScript:
```javascript
const modal = new bootstrap.Modal('#exampleModal', {
backdrop: 'static',
keyboard: false
});
modal.show();
// Listen for events
document.getElementById('exampleModal').addEventListener('hidden.bs.modal', () => {
console.log('Modal closed');
});
```
Events: `show.bs.modal`, `shown.bs.modal`, `hide.bs.modal`, `hidden.bs.modal`, `hidePrevented.bs.modal`.
#### Offcanvas
Slide-in side panels (sidebars, mobile navigation):
```html
Sidebar
Sidebar content here.
```
Offcanvas defaults:
| Option | Default | Description |
|---|---|---|
| `backdrop` | `true` | Show backdrop behind offcanvas |
| `keyboard` | `true` | Close on Escape key |
| `scroll` | `false` | Allow body scrolling while offcanvas is open |
Placement classes: `.offcanvas-start` (left), `.offcanvas-end` (right), `.offcanvas-top`, `.offcanvas-bottom`.
Events: `show.bs.offcanvas`, `shown.bs.offcanvas`, `hide.bs.offcanvas`, `hidden.bs.offcanvas`, `hidePrevented.bs.offcanvas`.
#### Popover
Rich content tooltips (requires Popper.js):
```html
```
Initialize all popovers on the page:
```javascript
const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]');
const popoverList = [...popoverTriggerList].map(el => new bootstrap.Popover(el));
```
> [!WARNING]
> Popovers are **opt-in** — they are not initialized automatically. You must initialize them via JavaScript as shown above, even when using data attributes for configuration.
Events: `show.bs.popover`, `shown.bs.popover`, `hide.bs.popover`, `hidden.bs.popover`, `inserted.bs.popover`.
#### ScrollSpy
Automatically update navigation based on scroll position:
```html
```
Toasts must be initialized via JavaScript:
```javascript
const toastEl = document.getElementById('liveToast');
const toast = bootstrap.Toast.getOrCreateInstance(toastEl);
toast.show();
```
Events: `show.bs.toast`, `shown.bs.toast`, `hide.bs.toast`, `hidden.bs.toast`.
#### Tooltip
Hover hints (requires Popper.js):
```html
```
Initialize all tooltips:
```javascript
const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
const tooltipList = [...tooltipTriggerList].map(el => new bootstrap.Tooltip(el));
```
> [!WARNING]
> Like Popovers, Tooltips are **opt-in** and must be initialized via JavaScript. They are not activated by data attributes alone.
Events: `show.bs.tooltip`, `shown.bs.tooltip`, `hide.bs.tooltip`, `hidden.bs.tooltip`, `inserted.bs.tooltip`.
### Forms
Bootstrap provides styled form controls, layout options, and validation:
```html
```
Form control classes:
| Element | Class | Notes |
|---|---|---|
| Text inputs | `.form-control` | Also for `textarea`, `email`, `password`, etc. |
| Select | `.form-select` | Replaces default select styling |
| Checkbox / Radio | `.form-check-input` | Wrap in `.form-check` |
| Range | `.form-range` | Custom range slider |
| File input | `.form-control` | Styled file picker |
| Floating labels | `.form-floating` | Wrap around input + label |
| Input group | `.input-group` | Prepend/append text or buttons |
### Typography
```html
Display 1
This is a lead paragraph with larger text.
Highlighted
DeletedStrikethrough
Fine print
A well-known quote.
Someone in Source Title
```
### Utilities
Bootstrap generates dozens of utility classes for rapid styling:
```html
Margin top 3, margin bottom 5, padding x 4
...
Primary text on light background
Bordered element
Hidden on mobile, visible on md+
Visible on mobile, hidden on md+
Fixed top-left
Small shadow
Regular shadow
Large shadow
```
---
## 5. Common Tasks
### Responsive Navbar with Mobile Hamburger
```html
```
This navbar is horizontal on `lg` and above, and collapses to a hamburger menu on smaller screens.
### Modal with Form Submission
```html
