Skip to main content

Overview

JSidebar is a vertical navigation component that extends JavaFX’s VBox. It supports collapsible states, multiple visual variants, custom header/footer sections, and smooth animations.

Enumerations

CollapseMode

COMPACT
CollapseMode
Icons only - sidebar collapses to show only icons (width: 70px)
HIDDEN
CollapseMode
Completely hidden - sidebar collapses to zero width

SidebarVariant

DEFAULT
SidebarVariant
Dark/standard variant with default styling
LIGHT
SidebarVariant
Light variant with white background and borders

Constructor

JSidebar()
constructor
Creates a new sidebar with default settings (expanded, COMPACT mode, DEFAULT variant).

Methods

Items Management

getItems()
ObservableList<Node>
Returns the observable list of sidebar items.

Expand/Collapse

isExpanded()
boolean
Checks if the sidebar is currently expanded.
setExpanded(boolean expanded)
void
Sets the expanded/collapsed state with animation.
expandedProperty()
BooleanProperty
Property for the expanded state.

Collapse Mode

getCollapseMode()
CollapseMode
Gets the current collapse mode.
setCollapseMode(CollapseMode mode)
void
Sets the collapse behavior.
collapseModeProperty()
ObjectProperty<CollapseMode>
Property for the collapse mode.

Variant

setVariant(SidebarVariant variant)
void
Sets the visual variant of the sidebar.
setHeader(Node header)
void
Sets a custom header node. When set, the toggle button is hidden.
Sets a custom footer node at the bottom of the sidebar.
  • JSidebarItem - Individual navigation items for the sidebar

Style Classes

j-sidebar
String
Base style class applied to the sidebar container
sidebar-default
String
Applied when using DEFAULT variant
sidebar-light
String
Applied when using LIGHT variant
j-sidebar-header-content
String
Applied to the custom header content wrapper
j-sidebar-header
String
Applied to the top bar containing the toggle button
j-sidebar-toggle
String
Applied to the hamburger menu toggle button
j-sidebar-items
String
Applied to the items container
j-sidebar-scroll
String
Applied to the scroll pane wrapping the items
Applied to the footer container
collapsed
String
Applied when the sidebar is collapsed
compact
String
Applied when using COMPACT collapse mode
hidden
String
Applied when using HIDDEN collapse mode

Example Usage

// Create sidebar
JSidebar sidebar = new JSidebar();

// Add navigation items
sidebar.getItems().addAll(
    new JSidebarItem("Home", JIcon.HOME.view()),
    new JSidebarItem("Profile", JIcon.USER.view()),
    new JSidebarItem("Settings", JIcon.SETTINGS.view())
);

// Set first item as active
if (sidebar.getItems().get(0) instanceof JSidebarItem) {
    ((JSidebarItem) sidebar.getItems().get(0)).setActive(true);
}

// Configure variant
sidebar.setVariant(JSidebar.SidebarVariant.LIGHT);

// Set custom header (hides toggle button)
JLabel logo = new JLabel("MyApp");
logo.setStyle("-fx-font-size: 20px; -fx-padding: 20px;");
sidebar.setHeader(logo);

// Set footer
JButton logoutBtn = new JButton("Logout");
sidebar.setFooter(logoutBtn);

// Configure collapse mode
sidebar.setCollapseMode(JSidebar.CollapseMode.COMPACT);

// Toggle programmatically
sidebar.setExpanded(false);

// Bind to property
sidebar.expandedProperty().addListener((obs, old, expanded) -> {
    System.out.println("Sidebar " + (expanded ? "expanded" : "collapsed"));
});

Behavior Notes

  • Collapse mode is automatically set based on item icons:
    • If any JSidebarItem has an icon, mode defaults to COMPACT
    • If no items have icons, mode defaults to HIDDEN
  • Animations run for 300ms when expanding/collapsing
  • Default widths:
    • Expanded: 250px
    • Compact: 70px
    • Hidden: 0px
  • The toggle button uses a hamburger menu icon from JIcon.MENU
  • When a custom header is set, the default toggle button is hidden
  • Items are scrollable if they exceed the available height

Dependencies

Source

com.jjarroyo.components.JSidebar in JSidebar.java:23

JSidebarItem

Overview

JSidebarItem is a navigation item component for use within JSidebar. It extends JavaFX’s HBox and displays an icon, label, and supports an active state.

Constructor

JSidebarItem(String text)
constructor
Creates a sidebar item with text only.
JSidebarItem(String text, Node icon)
constructor
Creates a sidebar item with text and icon.

Methods

setAction(Runnable action)
void
Sets the action to execute when the item is clicked.
setActive(boolean isActive)
void
Sets the active state of the item.
isActive()
boolean
Checks if the item is currently active.
activeProperty()
BooleanProperty
Property for the active state.
setIcon(Node icon)
void
Sets or updates the item icon.
getIcon()
Node
Gets the current icon.
getText()
String
Gets the item text.

Style Classes

j-sidebar-item
String
Base style class applied to the item container
j-sidebar-item-label
String
Applied to the text label
active
String
Applied when the item is in active state

Example Usage

// Create items with icons
JSidebarItem homeItem = new JSidebarItem("Home", JIcon.HOME.view());
homeItem.setAction(() -> navigateHome());
homeItem.setActive(true);

JSidebarItem profileItem = new JSidebarItem("Profile", JIcon.USER.view());
profileItem.setAction(() -> navigateProfile());

// Create item without icon
JSidebarItem settingsItem = new JSidebarItem("Settings");
settingsItem.setAction(() -> navigateSettings());

// Update icon later
settingsItem.setIcon(JIcon.SETTINGS.view());

// Bind to active state
profileItem.activeProperty().addListener((obs, old, active) -> {
    if (active) {
        System.out.println("Profile item activated");
    }
});

Behavior Notes

  • Items are clickable and trigger the action on mouse click
  • Active state adds the “active” CSS class for visual highlighting
  • Icons and labels are horizontally aligned with 12px spacing
  • A spacer region is added for future badge support on the right side

Source

com.jjarroyo.components.JSidebarItem in JSidebarItem.java:11

Build docs developers (and LLMs) love