Skip to content
WovenUI

Migrate from Bootstrap

Planning to migrate from Bootstrap to WovenUI? This guide maps Bootstrap classes and components to WovenUI core and the kit.

The kit covers the components most Bootstrap pages use. Class names follow one pattern: a wu- root, then bare words for variants and sizes (wu-btn brand sm), valid only together with the root. Layout helpers such as d-flex and gap-2 come from WovenUI core utility classes (flex, gap-2).

Class mapping

Section titled “Class mapping”

brand is the core color role, and the kit has no primary.

Bootstrap WovenUI Components Notes
<button class="btn btn-primary"> <button class="wu-btn brand"> On a <button> or a link
<button class="btn btn-danger"> <button class="wu-btn danger"> Destructive actions
<button class="btn btn-secondary"> <button class="wu-btn"> The plain button is the neutral one; btn-light maps the same way
<button class="btn btn-link"> <button class="wu-btn quiet"> Transparent until hover
btn-sm, btn-lg sm, lg wu-btn brand sm
<div class="btn-group"> <div class="wu-btn-group"> Pressed state from aria-pressed="true"
<div class="modal"> <dialog class="wu-modal"> Replaces modal-dialog and modal-content too; opened with commandfor and command="show-modal", no script
<div class="modal-header">, <div class="modal-body">, <div class="modal-footer"> <header class="wu-modal-header">, <div class="wu-modal-body">, <form class="wu-modal-footer"> The footer is a <form method="dialog">
<div class="offcanvas offcanvas-start"> <dialog class="wu-drawer"> Inline end by default; inline-start or bottom
<input class="form-control"> <input class="wu-input"> On a text-like <input>
<select class="form-select"> <select class="wu-select"> On a native <select>
<div class="form-check"> with <input class="form-check-input"> <label class="wu-checkbox"> Input and label are siblings in Bootstrap; here the label wraps <input class="wu-checkbox-input">
<div class="form-check form-switch"> <label class="wu-toggle"> Wraps <input class="wu-toggle-input" role="switch">
<div class="input-group"> <div class="wu-input-group"> Addons use wu-input-group-text
<ul class="dropdown-menu"> with <a class="dropdown-item"> <div class="wu-dropdown" popover> Items are wu-dropdown-item links or buttons; opened with popovertarget, no script
<hr class="dropdown-divider"> <hr class="wu-dropdown-separator"> Separator between items
<div class="alert alert-success"> <div class="wu-alert success"> Title in wu-alert-title; the marker shape repeats the role
<span class="badge text-bg-success"> <span class="wu-badge success"> Add solid for a filled badge
<div class="card"> <article class="wu-card"> Parts: <header class="wu-card-header">, <div class="wu-card-body">, <footer class="wu-card-footer">; heading in wu-card-title
<ul class="nav nav-tabs"> <div class="wu-tabs"> Parts wu-tabs-list, wu-tabs-tab, wu-tabs-panel; ARIA tabs; the kit script adds the keyboard
<div class="accordion"> <div class="wu-accordion"> Each item is <details class="wu-accordion-item">; no script
<div class="toast"> toast() from the kit script, or <div class="wu-toast"> Shown in a polite live region
<nav aria-label="breadcrumb"> <nav class="wu-breadcrumb"> Wraps <ol class="wu-breadcrumb-list">
<ul class="pagination"> <nav class="wu-pagination"> Bootstrap puts it inside a plain <nav>; here the <nav> wraps <ul class="wu-pagination-list"> of wu-btn links; aria-current="page" marks the current page
<div class="progress"> <progress class="wu-progress"> On a native <progress>
<div class="spinner-border"> <span class="wu-spinner"> Pair with role="status" and hidden text
<table class="table table-striped"> <table class="wu-table striped"> Also hover, bordered, sm
<button data-bs-toggle="popover"> <div class="wu-popover" popover> Native popover, no script

Modals and dropdowns without JavaScript

Section titled “Modals and dropdowns without JavaScript”

Bootstrap’s modal, offcanvas, dropdown, collapse and popover components each need a JavaScript plugin, and the dropdown and popover also need Popper for positioning. With the kit you can drop modal.js, offcanvas.js, dropdown.js, collapse.js and popover.js, and Popper with them, for these components. The browser does the work instead: modal and drawer are a <dialog>, dropdown and popover use the popover attribute, and the accordion is <details>. Bootstrap’s tooltip plugin is replaced by core tooltips. Keep Bootstrap’s script only for parts the kit does not cover, such as carousels.

What differs on purpose

Section titled “What differs on purpose”
  • Native elements. Modals and drawers are <dialog>, menus and popovers use the popover attribute, and accordions are <details>. The browser handles focus, Esc and the top layer, so most components need no JavaScript.
  • No icon set. The kit ships no icons. Markers such as the select arrow, the check mark and the close cross are drawn in CSS; bring your own icons for buttons and menus.
  • Tooltips live in core. Add data-tooltip to any element; see core tooltips.
  • State lives in attributes. Selected, pressed and sorted states come from aria-selected, aria-pressed, aria-sort and hidden, not from extra classes.
  • Themes come from tokens. Every component reads core --wu-* tokens, so light, dark, inverse and high contrast need no extra classes.

Migration checklist

Section titled “Migration checklist”
  1. Install the kit. Load the bundle or per-component entries, not both.
  2. Replace layout and helper classes with core utilities, using the first table.
  3. Swap components one at a time with the component table. Keep the old CSS loaded until the last one is gone.
  4. Move colors and spacing to core tokens, and switch themes with data-theme.
  5. Remove the old framework’s CSS and script.

Next steps

Section titled “Next steps”