About

Migrating from Bootstrap 2 to Bootstrap 3 involves hundreds of breaking changes across CSS class names, LESS/Sass variables, grid systems, and HTML structure. The grid alone shifted from span* to col-md-*, row-fluid became simply row, and the responsive utilities were entirely renamed. Missing a single class rename in a large codebase causes silent layout failures that are difficult to trace. This tool performs a multi-pass conversion covering class renames, variable migration (camelCase to dashed-base), icon class translation (icon-* → glyphicon glyphicon-*), and structural HTML changes. It processes CSS, HTML, LESS, Sass, and template files. The converter handles approximately 180 class mappings and 120 variable mappings extracted from the official Bootstrap 3 migration guide. Note: dynamically constructed class strings in JavaScript or server-side templates cannot be statically analyzed. The tool flags ambiguous matches for manual review rather than silently producing incorrect output.

Formulas

The converter operates as a multi-pass text transformation pipeline. Each pass applies a category of regular expression substitutions.

Output = P₄ ∘ P₃ ∘ P₂ ∘ P₁(Input)

Where P₁ = Variable conversion pass, P₂ = CSS class rename pass, P₃ = HTML structural pass, P₄ = Grid system pass.

Class replacement uses boundary-aware matching to avoid partial substitutions. For a class mapping old → new, the regex pattern is constructed as:

regex = (?<=["'\s])old(?=["'\s])

This ensures span6 inside a class attribute is matched but colspan6 is not. The diff algorithm compares input and output arrays line by line, marking lines as ADDED, REMOVED, or UNCHANGED, and produces a unified diff view with context lines.

Reference Data

Bootstrap 2 Class	Bootstrap 3 Equivalent	Category
row-fluid	row	Grid
span1 - span12	col-md-1 - col-md-12	Grid
container-fluid	container-fluid (unchanged)	Grid
brand	navbar-brand	Navbar
nav-collapse	navbar-collapse	Navbar
nav-toggle	navbar-toggle	Navbar
btn-navbar	navbar-btn	Navbar
hero-unit	jumbotron	Components
icon-*	glyphicon glyphicon-*	Icons
btn (alone)	btn btn-default	Buttons
btn-mini	btn-xs	Buttons
btn-small	btn-sm	Buttons
btn-large	btn-lg	Buttons
alert-error	alert-danger	Alerts
control-group	form-group	Forms
controls	(removed, use form-group)	Forms
input-block-level	form-control	Forms
input-mini	input-xs (custom)	Forms
input-small	input-sm	Forms
input-large	input-lg	Forms
input-xlarge	input-lg	Forms
input-xxlarge	input-lg	Forms
input-prepend	input-group	Forms
input-append	input-group	Forms
add-on	input-group-addon	Forms
thumbnail	img-thumbnail	Images
unstyled	list-unstyled	Typography
inline (on ul)	list-inline	Typography
muted	text-muted	Typography
label (component)	label label-default	Labels
label-important	label-danger	Labels
bar (progress)	progress-bar	Progress
bar-danger	progress-bar-danger	Progress
bar-warning	progress-bar-warning	Progress
bar-success	progress-bar-success	Progress
bar-info	progress-bar-info	Progress
accordion	panel-group	Panels
accordion-group	panel panel-default	Panels
accordion-heading	panel-heading	Panels
accordion-body	panel-collapse	Panels
accordion-inner	panel-body	Panels
visible-phone	visible-xs	Responsive
visible-tablet	visible-sm	Responsive
visible-desktop	visible-md visible-lg	Responsive
hidden-phone	hidden-xs	Responsive
hidden-tablet	hidden-sm	Responsive
hidden-desktop	hidden-md hidden-lg	Responsive
.img-polaroid	.img-thumbnail	Images

Frequently Asked Questions

The converter uses context-aware matching. Classes like bar are only replaced when found within a .progress context or adjacent to other Bootstrap progress classes. Standalone occurrences of bar in CSS selectors or HTML are flagged in the summary as "Ambiguous - manual review recommended" rather than auto-replaced. The same logic applies to brand, label, and other common English words used as Bootstrap 2 class names.

Yes. The variable pass detects both @variable (LESS) and $variable (Sass/SCSS) prefixes. It converts camelCase variable names to dashed-base equivalents (e.g., @baseFontSize becomes @font-size-base). Variables removed in Bootstrap 3 are commented out with a note indicating the removal. Approximately 120 variable mappings are included from the official migration documentation.

In HTML class attributes, icon-search is replaced with glyphicon glyphicon-search and the <i> tag is changed to <span>. However, in JavaScript strings like $('.icon-search'), the converter flags the line but does not auto-replace, because the CSS selector syntax differs from class attribute syntax. The summary report lists all such occurrences with line numbers for manual correction.

The converter preserves template expressions (<%= %>, {{ }}, <% %>) by temporarily replacing them with unique placeholder tokens before processing. After all passes complete, tokens are restored to their original template expressions. This prevents the regex engine from matching partial class names inside dynamic expressions. However, dynamically constructed class strings inside template logic blocks cannot be statically analyzed and are skipped.

By default, span* classes map to col-md-* as the closest semantic equivalent to Bootstrap 2's default grid. The tool provides a dropdown option to select the target breakpoint prefix (col-xs-, col-sm-, col-md-, or col-lg-). Additionally, offset* becomes col-md-offset-* using the same selected prefix. The row-fluid class always becomes row regardless of the selected prefix, since Bootstrap 3 uses a single fluid grid system.

The converter processes files up to approximately 500 KB in under 200 ms on modern hardware. Files between 500 KB and 2 MB trigger a progress indicator. The processing is synchronous on the main thread since Web Workers cannot access the DOM mappings efficiently for this workload size. For very large codebases, process files individually rather than concatenating them.