1. Overview
The Oorian Bootstrap Library provides a complete Java wrapper around Bootstrap 5, the most popular CSS framework for building responsive, mobile-first websites. It enables Oorian developers to use Bootstrap's full component library entirely in Java, following the Oorian philosophy of pure server-side development.
Key Features
- Full Java API for Bootstrap 5 components: buttons, cards, forms, modals, navigation, and more
- Responsive grid system with
BsContainer,BsRow, andBsCol - Type-safe enums for variants, sizes, breakpoints, and positions
- Interactive components: modals, accordions, carousels, dropdowns, tooltips, toasts, and popovers
- Form controls with built-in validation states
- All components extend
StyledElementwith full access to Oorian's styling API - Fluent method chaining on all setter methods
- CDN or local resource loading
2. Getting Started
Required Files
The Bootstrap extension consists of four components:
| File | Description |
|---|---|
oorian-bootstrap-x.y.z.jar |
The Oorian Bootstrap library JAR. Add this to your web application's classpath (e.g., WEB-INF/lib). Available from the downloads page. |
oorian-bootstrap-x.y.z.js |
The Oorian-to-Bootstrap bridge script. This client-side file connects the Java API to the native Bootstrap library. Deploy it to your web application's public folder. Available from the downloads page. |
bootstrap.bundle.min.js |
The native Bootstrap JavaScript bundle (includes Popper.js). Download from the Bootstrap download page. |
bootstrap.min.css |
The Bootstrap CSS stylesheet. Download from the Bootstrap download page. |
Initialize the Library
In your page's createBody() method, call Bootstrap.initialize(this) to add all required CSS, JavaScript, and the initialization script.
@Override
protected void createBody(Body body)
{
Bootstrap.initialize(this);
}
That's it! The initialize() call adds the Bootstrap CSS and JavaScript to the page head, and the initialization script to the body. No JavaScript code is needed.
Custom Configuration (Optional)
If your files are in non-default locations, set the paths before calling initialize():
Bootstrap.setBootstrapRootPath("/assets/bootstrap");
Bootstrap.setOorianBootstrapJsPath("/assets/oorian");
Bootstrap.initialize(this);
Create a Component
After initializing the library, create Bootstrap components and add them to the page body.
BsButton btn = new BsButton("Click Me");
btn.setVariant(BsButton.PRIMARY);
btn.setSize(BsButton.SIZE_LARGE);
body.addElement(btn);
3. Layout & Grid System
Bootstrap's 12-column responsive grid is implemented through three classes: BsContainer, BsRow, and BsCol. These components generate the correct Bootstrap CSS classes for responsive layouts.
BsContainer
The container wraps your content and provides horizontal padding. Three modes are available:
// Fixed-width container (default)
BsContainer container = new BsContainer();
// Full-width fluid container
BsContainer fluid = new BsContainer().setFluid(true);
// Responsive container (full-width until breakpoint)
BsContainer responsive = new BsContainer().setBreakpoint(Breakpoint.MD);
BsRow
Rows hold columns and control spacing. Key methods:
| Method | CSS Class | Description |
|---|---|---|
setGutter(int) | g-{0-5} | Set both horizontal and vertical gutter |
setGutterX(int) | gx-{0-5} | Set horizontal gutter only |
setGutterY(int) | gy-{0-5} | Set vertical gutter only |
setRowCols(int) | row-cols-{n} | Set number of columns per row |
setRowCols(Breakpoint, int) | row-cols-{bp}-{n} | Set columns per row at breakpoint |
setAlignItems(String) | align-items-{value} | Vertical alignment (start, center, end) |
setJustifyContent(String) | justify-content-{value} | Horizontal justification |
BsCol
Columns define the width of your content within a row. The grid uses 12 units total.
// Auto-sizing column
BsCol auto = new BsCol();
// Fixed-size column (6 of 12 = 50%)
BsCol half = new BsCol(6);
// Responsive column with multiple breakpoints
BsCol responsive = new BsCol()
.setSize(12) // Full width on XS
.setSizeMd(6) // Half width on MD+
.setSizeLg(4) // Third width on LG+
.setOffset(Breakpoint.LG, 2) // Offset on LG+
.setOrder("first"); // Display order
BsCol provides convenience methods for each breakpoint: setSizeSm(), setSizeMd(), setSizeLg(), setSizeXl(), setSizeXxl(), as well as the generic setSize(Breakpoint, int) for any breakpoint.
Complete Grid Example
BsContainer container = new BsContainer();
BsRow row = new BsRow().setGutter(3);
BsCol sidebar = new BsCol().setSizeMd(3);
sidebar.addElement(sidebarContent);
BsCol main = new BsCol().setSizeMd(9);
main.addElement(mainContent);
row.addElement(sidebar);
row.addElement(main);
container.addElement(row);
body.addElement(container);
5. Forms & Inputs
The forms package provides Bootstrap-styled form controls with built-in validation support. Each form component renders the correct Bootstrap HTML structure including labels, inputs, and feedback messages.
BsInput
A versatile text input supporting 15 HTML input types via the InputType enum:
BsInput email = new BsInput()
.setType(InputType.EMAIL)
.setName("email")
.setPlaceholder("Enter your email")
.setSize(Size.LG)
.setRequired(true)
.setValidFeedback("Looks good!")
.setInvalidFeedback("Please enter a valid email.")
.setValidationState(ValidationState.INVALID);
BsFormGroup
Wraps a label and input together with proper spacing:
BsFormGroup group = new BsFormGroup("Email Address")
.setFloating(true) // Use floating labels
.setMarginBottom(4); // mb-4 spacing
group.addElement(emailInput);
BsSelect
BsSelect select = new BsSelect()
.setName("country")
.setSize(Size.MD)
.setRequired(true)
.addPlaceholder("Select a country...")
.addOption("us", "United States")
.addOption("uk", "United Kingdom")
.addOption("ca", "Canada", true); // Pre-selected
BsCheckbox, BsRadio, BsSwitch
// Checkbox
BsCheckbox check = new BsCheckbox("Remember me")
.setChecked(true)
.setInline(true)
.setName("remember")
.setValue("yes");
// Radio buttons (same name groups them)
BsRadio option1 = new BsRadio("Option A")
.setName("choice").setValue("a").setChecked(true);
BsRadio option2 = new BsRadio("Option B")
.setName("choice").setValue("b");
// Toggle switch
BsSwitch toggle = new BsSwitch("Enable notifications")
.setChecked(true)
.setName("notifications");
BsTextarea
BsTextarea textarea = new BsTextarea()
.setName("message")
.setRows(5)
.setPlaceholder("Enter your message...")
.setRequired(true)
.setReadOnly(false);
BsFormLabel
BsFormLabel label = new BsFormLabel("Email")
.setFor("emailInput") // Associates with input ID
.setColLabel(3); // For horizontal forms: col-sm-3
6. Cards
The BsCard component is a flexible container for content with optional headers, footers, images, and color variants. It automatically builds the Bootstrap card structure with card-header, card-body, and card-footer child elements.
Basic Card
BsCard card = new BsCard()
.setHeader("Featured Article")
.setBody(articleContent)
.setFooter("Posted 2 days ago")
.setShadow(true);
Card with Image
BsCard imageCard = new BsCard()
.setImage("/img/product.jpg")
.setImageTop(true) // true = top, false = bottom
.setBody(productDetails)
.setFooter(buyButton);
Styled Card
BsCard styled = new BsCard()
.setBgVariant(Variant.DARK) // Dark background
.setTextVariant(Variant.LIGHT) // Light text
.setBorderVariant(Variant.PRIMARY) // Primary border
.setShadow(true)
.setShadowSize("lg") // sm, lg, or null for default
.setHeader("Dark Card")
.setBody(content);
Card Sub-Components
You can also use BsCardHeader, BsCardBody, and BsCardFooter directly for custom card layouts:
BsCard custom = new BsCard();
BsCardHeader header = new BsCardHeader("Custom Header");
BsCardBody body = new BsCardBody();
body.addElement(myContent);
BsCardFooter footer = new BsCardFooter("Footer text");
custom.addElement(header);
custom.addElement(body);
custom.addElement(footer);
8. Interactive Components
These components require Bootstrap's JavaScript bundle for full functionality. The BootstrapInitScript is automatically added to the page when any BootstrapComponent is initialized.
BsModal
A dialog overlay with configurable size, position, backdrop behavior, and keyboard interaction.
BsModal modal = new BsModal()
.setTitle("Confirm Action")
.setBodyText("Are you sure you want to proceed?")
.setSize(Size.LG) // SM, LG, XL
.setCentered(true) // Vertically centered
.setScrollable(true) // Scrollable body
.setStaticBackdrop(true) // Prevent backdrop click close
.setKeyboard(false) // Disable ESC to close
.setFade(true) // Fade animation
.setFullscreen(false);
// Create a trigger button automatically linked to this modal
BsButton trigger = modal.createTriggerButton("Open Modal");
// Or set body with custom content
modal.setBody(customElement);
modal.setFooter(footerButtons);
BsAccordion
BsAccordion accordion = new BsAccordion()
.setFlush(true) // No outer borders
.setAlwaysOpen(false); // true = multiple panels open at once
accordion.addItem("Section 1", contentElement1, true); // expanded
accordion.addItem("Section 2", "Plain text content", false);
accordion.addItem("Section 3", contentElement3, false);
BsCarousel
BsCarousel carousel = new BsCarousel()
.setControls(true) // Prev/next arrows
.setIndicators(true) // Dot indicators
.setFade(true) // Crossfade transition
.setAutoplay(true)
.setInterval(3000) // 3 seconds per slide
.setTouch(true) // Swipe support
.setDark(true); // Dark controls
carousel.addSlide("/img/slide1.jpg", "First Slide", "Description text");
carousel.addSlide("/img/slide2.jpg", "Alt text");
carousel.addSlide(customElement); // Custom content slide
carousel.addSlideWithInterval("/img/slide3.jpg", "Alt", 7000);
BsCollapse
BsCollapse collapse = new BsCollapse()
.setContent(hiddenContent)
.setHorizontal(false)
.setExpanded(false); // Initially collapsed
// Create trigger button or link
BsButton triggerBtn = collapse.createTriggerButton("Toggle");
Anchor triggerLink = collapse.createTriggerLink("Show More");
BsDropdown
BsDropdown dropdown = new BsDropdown("Actions", Variant.PRIMARY)
.setDirection("down") // up, down, start, end
.setSplit(false) // true = split button dropdown
.setMenuAlign("end") // Right-aligned menu
.setDark(true) // Dark menu theme
.addHeader("Actions")
.addItem("Edit", "/edit")
.addActiveItem("View", "/view")
.addDivider()
.addItem("Delete", "/delete")
.addDisabledItem("Archive");
BsOffcanvas
BsOffcanvas offcanvas = new BsOffcanvas()
.setTitle("Sidebar Menu")
.setPlacement("start") // start, end, top, bottom
.setBackdrop(true)
.setScroll(false) // Allow body scroll when open
.setKeyboard(true); // ESC to close
offcanvas.getBody().addElement(menuContent);
BsButton trigger = offcanvas.createTriggerButton("Open Menu");
BsTooltip & BsPopover
// Tooltip: lightweight text hint
BsTooltip tooltip = new BsTooltip("Helpful information")
.setPlacement("top") // top, bottom, left, right
.setTrigger("hover focus")
.setHtml(false)
.setDelay(200);
tooltip.addElement(targetButton);
// Popover: richer content overlay
BsPopover popover = new BsPopover("Title", "Detailed content here")
.setPlacement("right")
.setTrigger("click")
.setDismissible(true)
.setHtml(true)
.setCustomClass("my-popover");
popover.addElement(targetElement);
Initialization Required: Tooltips and popovers are opt-in in Bootstrap for performance reasons. They are initialized automatically via the oorian.bootstrap.js bridge script when you use Bootstrap.addAllResources(head).
BsToast
BsToast toast = new BsToast()
.setTitle("Notification")
.setSubtitle("Just now")
.setBody("Your changes have been saved successfully.")
.setHeaderIcon("bi bi-check-circle text-success")
.setAutohide(true)
.setDelay(5000) // 5 seconds
.setAnimation(true);
9. Display Components
BsTable
A Bootstrap-styled table with convenience methods for adding header and data rows programmatically.
BsTable table = new BsTable()
.setStriped(true) // Alternating row colors
.setStripedColumns(false) // Alternating column colors
.setBordered(true) // All borders
.setHover(true) // Row hover highlight
.setSmall(true) // Compact padding
.setVariant(Variant.DARK); // Dark theme
table.addHeaderRow("Name", "Email", "Role");
table.addRow("Alice", "alice@example.com", "Admin");
table.addRow("Bob", "bob@example.com", "Editor");
table.addRow("Charlie", "charlie@example.com", "Viewer");
BsListGroup
BsListGroup list = new BsListGroup()
.setFlush(true) // No outer borders
.setNumbered(true) // Numbered (renders as <ol>)
.setHorizontal(false);
list.addItem("First item");
list.addItem("Active item", true, false); // active, not disabled
list.addItem("Disabled item", false, true); // not active, disabled
list.addItem("Colored item", Variant.SUCCESS);
list.addItem(customElement); // Element as item
BsSpinner
// Border spinner (default)
BsSpinner spinner = new BsSpinner()
.setVariant(Variant.PRIMARY)
.setSmall(true);
// Grow spinner
BsSpinner grow = new BsSpinner()
.setGrow(true)
.setVariant(Variant.SUCCESS);
BsPlaceholder
Used for loading skeleton screens:
BsPlaceholder placeholder = new BsPlaceholder()
.setWidth(6) // col-6 width
.setSize(Size.LG)
.setVariant(Variant.PRIMARY)
.setAnimation("glow"); // "glow" or "wave"
// Extra small placeholder
BsPlaceholder xs = new BsPlaceholder().setExtraSmall();
10. Alerts, Badges & Progress
BsAlert
Contextual alert messages with optional dismiss functionality:
// Simple alert
BsAlert alert = new BsAlert("Operation completed successfully!")
.setVariant(Variant.SUCCESS);
// Dismissible alert
BsAlert dismissible = new BsAlert("Click X to dismiss this alert.")
.setVariant(Variant.WARNING)
.setDismissible(true); // Adds close button, fade, show classes
// Alert with custom content
BsAlert custom = new BsAlert()
.setVariant(Variant.INFO)
.setContent(richContentElement);
BsBadge
// Standard badge
BsBadge badge = new BsBadge("New")
.setVariant(Variant.DANGER);
// Pill badge (rounded)
BsBadge pill = new BsBadge("42")
.setVariant(Variant.PRIMARY)
.setPill(true);
BsProgress
A progress bar with optional stripes, animation, and labels:
BsProgress progress = new BsProgress(75)
.setVariant(Variant.SUCCESS)
.setStriped(true)
.setAnimated(true) // Animated stripes (auto-enables striped)
.setShowLabel(true) // Shows "75%"
.setMin(0)
.setMax(100);
// Custom label
BsProgress custom = new BsProgress()
.setValue(3)
.setMax(10)
.setLabel("3 of 10 completed")
.setVariant(Variant.INFO);
11. Enums Reference
The library provides seven type-safe enums in the com.oorian.bootstrap.enums package. These enums replace magic strings and ensure compile-time safety when configuring Bootstrap components.
Variant
Color variants used across buttons, alerts, badges, cards, tables, spinners, and progress bars.
| Constant | CSS Value | Typical Use |
|---|---|---|
Variant.PRIMARY | "primary" | Primary actions, key UI elements |
Variant.SECONDARY | "secondary" | Secondary actions |
Variant.SUCCESS | "success" | Success states, confirmations |
Variant.DANGER | "danger" | Errors, destructive actions |
Variant.WARNING | "warning" | Caution, warnings |
Variant.INFO | "info" | Informational messages |
Variant.LIGHT | "light" | Light backgrounds |
Variant.DARK | "dark" | Dark backgrounds |
Variant.LINK | "link" | Link-styled buttons |
Size
| Constant | CSS Value | Description |
|---|---|---|
Size.SM | "sm" | Small size |
Size.MD | "" (default) | Medium / default size. isDefault() returns true. |
Size.LG | "lg" | Large size |
Size.XL | "xl" | Extra large (used by modals) |
Breakpoint
| Constant | CSS Infix | Min Width |
|---|---|---|
Breakpoint.XS | "" | 0px (all screens) |
Breakpoint.SM | "-sm" | 576px |
Breakpoint.MD | "-md" | 768px |
Breakpoint.LG | "-lg" | 992px |
Breakpoint.XL | "-xl" | 1200px |
Breakpoint.XXL | "-xxl" | 1400px |
Methods: getValue() returns the suffix string, getMinWidth() returns the pixel threshold, and getInfix() returns the dash-prefixed infix (e.g., "-md") for building responsive class names.
InputType
Used with BsInput.setType(). Supported types: TEXT, PASSWORD, EMAIL, NUMBER, TEL, URL, SEARCH, DATE, TIME, DATETIME_LOCAL, MONTH, WEEK, COLOR, FILE, HIDDEN.
Other Enums
| Enum | Values | Used By |
|---|---|---|
Direction | HORIZONTAL, VERTICAL | BsButtonGroup |
Position | TOP, BOTTOM, START, END, LEFT, RIGHT | Tooltips, popovers |
ValidationState | NONE, VALID, INVALID | BsInput, BsSelect, BsTextarea |
12. Complete Examples
Login Page
@Page("/login")
public class LoginPage extends HtmlPage
{
@Override
protected void createHead(Head head)
{
head.setTitle("Login");
Bootstrap.addAllResources(head);
}
@Override
protected void createBody(Body body)
{
BsContainer container = new BsContainer();
BsRow row = new BsRow().setJustifyContent("center");
BsCol col = new BsCol().setSizeMd(6).setSizeLg(4);
BsCard card = new BsCard().setShadow(true);
Div cardBody = new Div();
H3 title = new H3();
title.setText("Sign In");
title.addClass("text-center mb-4");
cardBody.addElement(title);
// Email field
BsFormGroup emailGroup = new BsFormGroup("Email address");
BsInput emailInput = new BsInput()
.setType(InputType.EMAIL)
.setName("email")
.setPlaceholder("name@example.com")
.setRequired(true);
emailGroup.addElement(emailInput);
cardBody.addElement(emailGroup);
// Password field
BsFormGroup passGroup = new BsFormGroup("Password");
BsInput passInput = new BsInput()
.setType(InputType.PASSWORD)
.setName("password")
.setPlaceholder("Enter password")
.setRequired(true);
passGroup.addElement(passInput);
cardBody.addElement(passGroup);
// Remember me
BsCheckbox remember = new BsCheckbox("Remember me");
cardBody.addElement(remember);
// Submit button
BsButton submit = new BsButton("Sign In")
.setVariant(Variant.PRIMARY)
.setType("submit")
.setBlock(true);
submit.addClass("mt-3");
cardBody.addElement(submit);
card.setBody(cardBody);
col.addElement(card);
row.addElement(col);
container.addElement(row);
body.addElement(container);
}
}
Dashboard Layout
@Page("/dashboard")
public class DashboardPage extends HtmlPage
{
@Override
protected void createHead(Head head)
{
head.setTitle("Dashboard");
Bootstrap.addAllResources(head);
}
@Override
protected void createBody(Body body)
{
// Navbar
BsNavbar navbar = new BsNavbar()
.setBrand("Dashboard", "/")
.setVariant(Variant.DARK)
.setBackground("bg-dark");
body.addElement(navbar);
// Main content
BsContainer container = new BsContainer().setFluid(true);
container.addClass("mt-4");
// Breadcrumb
BsBreadcrumb breadcrumb = new BsBreadcrumb()
.addItem("Home", "/")
.addItem("Dashboard", null);
container.addElement(breadcrumb);
// Stats cards row
BsRow statsRow = new BsRow().setGutter(3);
statsRow.addElement(createStatCard("Users", "1,234", Variant.PRIMARY));
statsRow.addElement(createStatCard("Revenue", "$5,678", Variant.SUCCESS));
statsRow.addElement(createStatCard("Orders", "89", Variant.INFO));
statsRow.addElement(createStatCard("Issues", "3", Variant.WARNING));
container.addElement(statsRow);
// Data table
BsTable table = new BsTable()
.setStriped(true).setHover(true).setBordered(true);
table.addHeaderRow("ID", "Name", "Status", "Date");
table.addRow("1", "Project Alpha", "Active", "2026-01-15");
table.addRow("2", "Project Beta", "Pending", "2026-02-01");
container.addElement(table);
body.addElement(container);
}
private BsCol createStatCard(String label, String value, Variant variant)
{
BsCol col = new BsCol().setSizeMd(3).setSize(6);
Div content = new Div();
H4 valueH4 = new H4();
valueH4.setText(value);
content.addElement(valueH4);
Paragraph labelP = new Paragraph();
labelP.setText(label);
content.addElement(labelP);
BsCard card = new BsCard()
.setBorderVariant(variant)
.setBody(content)
.setShadow(true).setShadowSize("sm");
col.addElement(card);
return col;
}
}
Component Class Hierarchy
All Bootstrap components follow the same inheritance chain: StyledElement<T> (Oorian Core) extends to BootstrapComponent<T> (base class), which extends to the 40+ concrete components (BsButton, BsCard, BsModal, BsNav, etc.).
Full API Coverage: This library wraps 40+ Bootstrap components across 10 packages, including all major layout, form, navigation, and interactive components. Every method supports fluent chaining for clean, readable code. Because all components extend Oorian's StyledElement, you can freely mix Bootstrap components with standard Oorian elements and other UI extension libraries.
Quick Reference: All Components
| Component | HTML Tag | Key Methods |
|---|---|---|
BsAlert | <div> | setVariant(), setDismissible(), setContent() |
BsBadge | <span> | setVariant(), setPill() |
BsButton | <button> | setVariant(), setSize(), setOutline(), setBlock(), setActive(), setType() |
BsButtonGroup | <div> | setSize(), setVertical(), setDirection(), setAriaLabel() |
BsCard | <div> | setHeader(), setBody(), setFooter(), setImage(), setShadow(), setBgVariant() |
BsContainer | <div> | setFluid(), setBreakpoint() |
BsRow | <div> | setGutter(), setRowCols(), setAlignItems(), setJustifyContent() |
BsCol | <div> | setSize(), setSizeMd/Lg/Xl(), setOffset(), setOrder(), setAlignSelf() |
BsInput | <div> | setType(), setSize(), setPlaceholder(), setValidationState() |
BsSelect | <select> | addOption(), addPlaceholder(), setMultiple(), setSize() |
BsCheckbox | <div> | setChecked(), setInline(), setName(), setValue() |
BsRadio | <div> | setChecked(), setInline(), setName(), setValue() |
BsSwitch | <div> | setChecked(), setName(), setValue() |
BsTextarea | <textarea> | setRows(), setPlaceholder(), setValidationState() |
BsNav | <ul> | setPills(), setTabs(), setFill(), setVertical() |
BsNavItem | <li> | setActive() |
BsNavbar | <nav> | setBrand(), setExpandBreakpoint(), setVariant(), setFixed(), setHoverDropdowns() |
BsTabs | <div> | addTab(), addDisabledTab(), setPills(), setFill(), setFade(), setVertical() |
BsBreadcrumb | <nav> | addItem(), setDivider() |
BsPagination | <nav> | setTotalPages(), setCurrentPage(), setBaseUrl(), setSize() |
BsModal | <div> | setTitle(), setBody(), setSize(), setCentered(), createTriggerButton() |
BsAccordion | <div> | addItem(), setFlush(), setAlwaysOpen() |
BsCarousel | <div> | addSlide(), setControls(), setIndicators(), setFade(), setAutoplay() |
BsCollapse | <div> | setContent(), setHorizontal(), createTriggerButton(), createTriggerLink() |
BsDropdown | <div> | addItem(), addDivider(), addHeader(), setSplit(), setDirection() |
BsOffcanvas | <div> | setTitle(), setPlacement(), getBody(), createTriggerButton() |
BsPopover | <span> | setTitle(), setContent(), setPlacement(), setTrigger(), setDismissible() |
BsToast | <div> | setTitle(), setBody(), setAutohide(), setDelay(), setHeaderIcon() |
BsTooltip | <span> | setTitle(), setPlacement(), setTrigger(), setHtml(), setDelay() |
BsTable | <table> | addHeaderRow(), addRow(), setStriped(), setBordered(), setHover() |
BsListGroup | <ul> | addItem(), setFlush(), setNumbered(), setHorizontal() |
BsSpinner | <div> | setGrow(), setSmall(), setVariant() |
BsPlaceholder | <span> | setWidth(), setSize(), setVariant(), setAnimation() |
BsProgress | <div> | setValue(), setMin(), setMax(), setVariant(), setStriped(), setAnimated() |