Bootstrap WC Addon documantation

📖 Introduction

bootstrap-wc-addon is a lightweight library of Web Components built on top of Bootstrap 5. Unlike many Web Component libraries, it does not use Shadow DOM.

This means:

All markup is rendered in the light DOM.
You can fully style the components using your own CSS or standard Bootstrap utility classes.
No encapsulation barriers → your global styles, theme variables, and existing Bootstrap setup apply directly.

The library is designed to feel like a natural extension of Bootstrap::

Custom elements (bs-navbar, bs-hero, bs-carousel, etc.)
Simple declarative attributes (e.g. title, background, variant)
Compatible with Bootstrap 5's CSS and JavaScript
Flexible enough to integrate with any frontend stack without extra configuration

👉 In short: All the power of Bootstrap, with the convenience of custom HTML tags, and no Shadow DOM restrictions.

❗Notice! To modify web components you need to target the node inside the component. Here is an example for <bs-button>.

const exampleBtn = document.getElementById('example')
const internalBtn = exampleBtn.querySelector('button');

console.log(exampleBtn);	<bs-button id="example" variant="primary"></bs-button>
console.log(internalBtn);	<button id="example" class="btn btn-primary btn- " type="button" false="">

Accordion

tag name: bs-accordion

Example

Code

<bs-accordion items='[
	{"title":"Title","content":"Lorem ipsum dolor sit amet consectetur adipisicing elit. Pariatur voluptates, quasi aut hic accusantium nam itaque aliquid, eaque laudantium odit consequatur illo vero atque. Asperiores quod sit molestias quia iusto."},
	{"content":"Lorem ipsum dolor sit amet consectetur adipisicing elit. Pariatur voluptates, quasi aut hic accusantium nam itaque aliquid, eaque laudantium odit consequatur illo vero atque. Asperiores quod sit molestias quia iusto."},
	{"content":"Lorem ipsum dolor sit amet consectetur adipisicing elit. Pariatur voluptates, quasi aut hic accusantium nam itaque aliquid, eaque laudantium odit consequatur illo vero atque. Asperiores quod sit molestias quia iusto."}
]'></bs-accordion>

Copy

Attributes

Attribute	Type	Description	Alternatives	Default
class	string	HTML class attribute.		""
id	string	HTML id attribute.		""
label	string	Label text.		""
openindex	number (string)	Specifies which accordion item should be open (expanded) by default. The index starts at 0.	any index number present	0

Button

tag name: bs-button

Example

Click me

Code

<bs-button id="example" variant="primary">Click me</bs-button>

Copy

Attributes

Attribute	Type	Description	Alternatives	Default
class	string	HTML class attribute.		""
disabled	boolean	Disables button.		false
id	string	HTML id attribute.		""
label	string	Button text.		""
size	string	Bootstrap classes	"sm", "lg"	""
type	string	HTML button type.	"button", "submit", "reset"	""
variant	string	Bootstrap classes.	"primary", "secondary", "success", "danger", "warning", "info", "light", "dark", "link"	""

Carousel

tag name: bs-carousel

Example

Code

<bs-carousel autoplay controls indicators height="200px" class="carousel-fade" images='[
	{"src":"https://images.pexels.com/photos/1563356/pexels-photo-1563356.jpeg","alt":"road","caption":{"label":"label","content":"content"}},
	{"src":"https://images.pexels.com/photos/247851/pexels-photo-247851.jpeg","alt":"free","caption":{"label":"label","content":"content"}},
	{"src":"https://images.pexels.com/photos/1906658/pexels-photo-1906658.jpeg","alt":"free", "interval": 500}
	]'>
</bs-carousel>

Copy

Attributes

Attribute	Type	Description	Alternatives	Default
images	string (JSON)	JSON array of image objects, optionally including captions.		[]
autoplay	boolean	Enables automatic sliding (Bootstrap `data-bs-ride`).	attribute without value	false
indicators	boolean	Show or hide the indicator dots.	attribute without value	false
controls	boolean	Show or hide the previous/next controls.	attribute without value	false
height	string	CSS height applied to carousel images.	any valid CSS size (px, %, em, etc.)	100%
width	string	CSS width applied to the carousel container.	any valid CSS size or percentage	100%
class	string	Extra CSS classes to add to the carousel container.		""

Dropdown

tag name: bs-dropdown

Description: A Bootstrap-powered dropdown component that automatically converts its children into bootstrap-styled dropdown items. Supports wrapper-level Bootstrap classes such as dropup, dropend, dropdown-center, and more.

⚠️ Note: You do not need to wrap your menu items in <li> tags — the component automatically wraps each child inside <li> and applies the dropdown-item class.

📌 ID Behavior: The id attribute is applied to the outer wrapper <div class="dropdown">, allowing direct DOM selection and integration with scripts.

Example

Code

<bs-dropdown label="Links" glossy class="dropdown-center" menu-class="shadow-lg">
    <a href="#one">page #1</a>
    <a href="#one">page #2</a>
    <a href="#one">page #3</a>
</bs-dropdown>

Copy

Attributes

Attribute	Type	Description	Alternatives	Default
label	string	Button label displayed on the toggle button		"Dropdown"
variant	string	Bootstrap color variant for the button	primary, secondary, success, danger, warning, info, light, dark	primary
size	string	Bootstrap button size	sm, lg	""
class	string	Extra Bootstrap classes applied to the outer wrapper (e.g. dropup, dropend, dropdown-center)		""
menu-class	string	Additional CSS classes applied directly to the dropdown-menu element		""
id	string	HTML id applied to the wrapper <div class="dropdown">		""
children	HTMLElement[]	Any child elements placed inside the component become dropdown items. Automatically wrapped in <li> and given the dropdown-item class.		none
glossy	boolean	Enables a glossy, semi-transparent visual style for the dropdown menu. Activated by adding the glossy attribute to the component. Applies blur/saturate effects and adjusted background/foreground colors.	<bs-dropdown glossy></bs-dropdown>	false

Hero

tag name: bs-hero

Example

Code

<bs-hero title="Example" height="200px"
	background="https://videos.pexels.com/video-files/3129671/3129671-uhd_2560_1440_30fps.mp4"
	textColor="light">
</bs-hero>

Copy

Attributes

Attribute	Type	Description	Alternatives	Default
title	string	Main headline text displayed in the hero.		""
subtitle	string	Optional subheadline text displayed below the title.		""
background	string	URL of the background media. If it ends with ".mp4", it will render as a looping video. Otherwise, it will be treated as an image URL.		""
text-color	string	Text color applied to title and subtitle. Uses Bootstrap text color classes.	"light", "dark", "primary", "secondary", "success", "danger", "warning", "info", "body", "muted", "white"	"light"
class	string	Additional CSS classes to apply to the hero container.		""
height	string	Height of hero.	any valid CSS size (px, %, em, vh, etc.)	`calc(100vh - nav height)`

Input

tag name: bs-input

Description: A versatile Bootstrap-styled input component that supports text, checkbox, radio, and select types with built-in validation.

⚠️ Important Note: When adding "submit" event listeners inside DOMContentLoaded for forms using the <bs-input> components, the built-in validation automatically stops submission of invalid forms. This ensures your custom listener only runs when the form is valid.

♿️ Accessibility Note: All <bs-input> and <bs-select> components automatically announce validation errors to screen readers using aria-live="polite" and role="alert". This ensures users with visual impairments are informed about invalid form inputs.

Example

Code

<form id="inputForm" class="needs-validation" novalidate>
    <bs-input type="text" name="firstName" label="First Name" placeholder="Enter first name" required class="mb-3"></bs-input>
    <bs-input type="checkbox" name="subscribe" label="Subscribe to newsletter" class="mb-3" required></bs-input>
    <bs-input type="radio" name="gender" label="Gender" options='[{"value":"male","label":"Male"},{"value":"female","label":"Female"}]' class="mb-3" required></bs-input>
    <bs-input type="select" label="Role" name="role" id="custom-select" class="col-md-5" placeholder="Select Position" options='[
        {"label": "Developer", "value": "1"},
        {"label": "UI/UX Designer", "value": "2"},
        {"label": "Tester", "value": "3"}
    ]' required></bs-input>
    <bs-button type="submit" variant="primary">Submit</bs-button>
    <bs-button type="reset" variant="secondary">Reset</bs-button>
</form>

<script>
document.addEventListener("DOMContentLoaded", () => {
    const inputForm = document.getElementById('inputForm');
    inputForm.addEventListener('submit', (e) => {
        e.preventDefault();
        const data = Object.fromEntries(new FormData(e.target));
        alert(JSON.stringify(data));
    });
});
</script>

Copy

Attributes

Attribute	Type	Description	Default
type	string	Type of input (text, checkbox, radio, select)	text
name	string	HTML name attribute used in forms	""
label	string	Text label displayed for the input	""
required	boolean (presence-based)	Marks the input as required	false
options	JSON array	For radio/select types: array of objects with value, label, optional selected	[]
placeholder	string	Placeholder text (for text input) or hidden option text (for select)	""
class	string	Extra CSS classes applied to the wrapper	""
disabled	boolean (presence-based)	Disable the input if present	false
id	string	HTML id attribute for the input element	""
pattern	string	Optional regex pattern that the input value must match. Only for text, password, tel, or search inputs.	""
error	string	Custom error message displayed for validation	""

Navbar

tag name: bs-navbar

Description: bs-navbar is a responsive navigation bar component that automatically manages the active state of its links. When a user clicks a link or scrolls through the page, the corresponding link is highlighted with the "active" class. This is achieved using the IntersectionObserver API, which detects which section of the page is currently in view.

Key Features

Automatically adds class "active" on click or scroll.
Automatically handles scroll-padding-top if navbar height is altered.
Smooth section tracking using IntersectionObserver.
Fully customizable via CSS variables.

Example (image)

Code

<bs-navbar brand="Bootstrap WC Addon" focus-color="primary"
				links='[{"href": "/", "label": "Home"}, {"Local": [{"href": "#top", "label": "Top"}, {"href": "#middle", "label":"Middle"}, {"href": "#bottom", "label": "Bottom"}]}, {"href": "https://www.anderssöderberg.se", "label": "External link", "target": "_blank"}]'>
</bs-navbar>

Copy

Attributes

Attribute	Type	Description	Alternatives	Default
brand	string	Main headline text displayed in the navbar.		"Bootstrap WC Addon"
links	JSON array	Array of link objects. Each object must include `href` and `label` for single links, or a key-value pair for dropdown menus where the key is the title and the value is an array of link objects.		[]
focus-color	string	Color for focus state of toggler and close button.	Any valid CSS color.	""

Select

tag name: bs-select

Example

Code

<bs-select name="test" id="custom-select" class="mb-3"
	options='[{"label": "One", "value": "1"}, {"label": "Two", "value": 2}, {"label": "Three", "value": 3,
	"selected":true}]'>
</bs-select>

Copy

Attributes

Attribute	Type	Description	Default
options	JSON array	Array of option objects. Each object can have `value`, `label`, and optional `selected` boolean.	[]
disabled	Boolean (presence-based)	Disable the select element if present.	false
id	string	HTML id attribute for the select element.	""
name	string	HTML name attribute for the select element, used in forms.	""
class	string	Extra CSS classes (applies to the wrapper of select element).	""
required	Boolean (presence-based)	Whether the input must be filled	"false"
label	string	Text label displayed for the select	""
placeholder	string (presence-based, not shown if not provided)	Default text inside the select on load	""

Spinner

tag name: bs-spinner

Example

Code

<bs-spinner color="primary" size="35px"></bs-spinner>

Copy

Attributes

Attribute	Type	Description	Alternatives	Default
type	string	Color of the spinner, maps to Bootstrap text color classes.	"primary", "secondary", "success", "danger", "warning", "info", "light", "dark"	"primary"
variant	string	Spinner variant.	"border", "grow"	"border"
size	string (CSS unit)	Custom size of the spinner. Can be set in px, rem, em, etc. Leave empty for default size.		""