ZK Bootstrap Helper

Author
Hawk Chen

Date
July 15, 2025

Version
ZK 9.6.0 or above

Introduction

Bootstrap is a powerful and popular CSS framework that brings responsive layout and utility classes to modern web applications. It serves as an excellent companion for ZK applications with the following key features:

• Responsive Grid System: Layout pages using Bootstrap's responsive grid system
• Utility Classes: Style pages efficiently with utility CSS classes
• WebJar Integration: Includes Bootstrap WebJar and CSS files automatically

To help ZK users leverage Bootstrap more easily, we introduce the ZK Bootstrap Helper — a ZK addon that simplifies the inclusion of Bootstrap CSS files across all ZK pages at the application scope. This addon automatically integrates Bootstrap with ZK applications, providing developers with access to Bootstrap’s features without manual configuration.

The addon is designed to be lightweight and configurable, allowing developers to include only the Bootstrap components they need while maintaining full compatibility with ZK’s existing styling.

Usage

Maven Setup

This add-on is available in the ZK CE Maven Repository.

Add the following dependency to your project's pom.xml:

<dependency>
    <groupId>org.zkoss.zkforge</groupId>
    <artifactId>bootstrap-helper</artifactId>
    <version>5.1.0</version>
</dependency>

Default Usage

By default, the addon automatically includes the following Bootstrap CSS files on all ZK pages:

• bootstrap-grid.min.css - The responsive grid system
• bootstrap-utilities.min.css - Utility CSS classes

No additional configuration in zk.xml is required for using the grid system and utility classes. Also note that bootstrap-reboot.css is not included by default as it may conflict with ZK's default styles.

Custom CSS Selection

In addition to the two default CSS files, you can include other Bootstrap CSS files by configuring the addon in your zk.xml:

<library-property>
    <name>org.zkoss.zkforge.bootstrap</name>
    <value>custom</value>
</library-property>
<library-property>
    <name>org.zkoss.zkforge.bootstrap.custom</name>
    <list>
        <value>grid</value>
        <value>utilities</value>
        <value>reboot</value>
    </list>
</library-property>

This allows you to load custom CSS files based on your specific needs.

Supported Custom Values

The custom values correspond to the *.min.css files available in the Bootstrap WebJar. The value is the part of filename between bootstrap- and .min.css, for example:

Custom Value	CSS File	Description
grid	bootstrap-grid.min.css	Responsive grid system only
utilities	bootstrap-utilities.min.css	Utility classes for spacing, colors, etc.
reboot	bootstrap-reboot.min.css	CSS reset and base styles

Available *.min.css files in Bootstrap 5.1.0:

• bootstrap-grid.min.css
• bootstrap-grid.rtl.min.css
• bootstrap-reboot.min.css
• bootstrap-reboot.rtl.min.css
• bootstrap-utilities.min.css
• bootstrap-utilities.rtl.min.css
• bootstrap.min.css
• bootstrap.rtl.min.css

Disabling Bootstrap CSS

To disable all automatic Bootstrap CSS inclusion:

<library-property>
    <name>org.zkoss.zkforge.bootstrap</name>
    <value>none</value>
</library-property>

Version Compatibility

The addon follows Bootstrap's major version numbering:

ZK Bootstrap Helper	Bootstrap
5.x	5.x
4.x	4.x

Example Application

Once the Bootstrap classes are included in your project, you can use them freely in your ZK pages. Here is an example application demonstrating how to use the Bootstrap grid system to design a responsive ZK layout: Use Bootstrap with ZK: Responsive Admin Template

Download

The ZK Bootstrap Helper is open source and freely available. You can access the source repository here.

Note that the project is a helper tool to facilitate using Bootstrap’s CSS within ZK applications. It does not include Bootstrap itself nor modify ZK directly.

Summary

The ZK Bootstrap Helper addon provides a seamless integration between ZK Framework and Bootstrap CSS, offering developers a simple way to leverage Bootstrap's responsive design capabilities in their ZK applications. With minimal configuration required and flexible customization options, it's an effective solution for modern ZK web application development.