Struts 2 How To Customize The Theme That Controls How A Struts 2 Tag Is Displayed In The Browser


I was working on a project where I needed to change how the Struts 2 checkboxlist tag was rendered. Struts 2 includes several themes (simple, xhtml, css_xhtml that determine how each Struts 2 user interface tag is rendered in the browser. From reading several references (see below), I learned that you can easily customize how a Struts 2 tag is displayed in the browser. This article will explain how I customized how the Struts 2 checkboxlist tag is rendered. You can apply the same method described in this article to customize how the other Struts 2 tags are displayed.

Struts 2 CheckBoxList Tag

The Struts 2 checkboxlist tag is used to display each element of a List as a separate check box. To learn more about how to use the checkboxlist tag see the references below.

Using the default Struts 2 themes (simple, xhtml, css_xhtml) each checkbox is rendered on the same line as long as the browser window's display width is wide enough. I needed each checkbox and its label to display on its own line.

For example below is what the checkboxlist tag looks like when rendered in the browser using the default simple theme.

CheckboxList Display

Notice how each checkbox and its label is on the same line for the width of the browser display window. When the tag runs out of room on one line it just wraps down to the next line, sometimes breaking the checkbox from its label.

After modifying the application to use a custom theme that inserts a html break tag after each label, the checkboxlist tag displays as follows.

CheckboxList Display

Now each checkbox and its label are on their own lines.

Example Application

I created a simple Struts 2 web application that demonstrates using a custom theme to change the default display of the checkboxlist tag. You can download the archived application at The example application was created using Eclipse 3.5 with the Maven 2 plugin. You should be able to import the archive download directly into Eclipse.

If you are not using Eclipse, unzip the download and if your Java IDE supports importing Maven projects import the unzipped project.

You can run the application using the Maven command mvn jetty:run in a command (terminal) window after navigating to the project's root folder (the location of Maven's pom.xml file). When you see "[INFO] Started Jetty Server" in the command window open a web browser and load this URL: http://localhost:8080/struts2customthemeexample/update-input.action

When the web page opens there will be a checkboxlist tag displayed similar to the above image.

To stop the Jetty server type CTRL-C in the command window.

Creating A Custom Struts 2 Theme

Each Struts 2 user interface tag has an associated template file the governs how Struts 2 writes the HTML to display that tag. You can find these templates in the Struts 2 core jar file. If you expand the Struts 2 core jar file you'll find folders named template.css_xhtml, template.simple, and template.xhtml. Those folders contain the templates for the three default Struts 2 themes.

In the example application I've specified that the checkboxlist tag should use the simple theme (see update-input.jsp in src/main/webapp/WEB-INF/content). The simple theme template for the checkboxlist tag is in the template.simple folder (in the Struts 2 core jar file). The template is appropriately named checkboxlist.ftl. Opening that file you'll see that there is only a space between each label and the next checkbox. That is why all the checkboxes are displayed across the width of the browser window.

For my custom checkboxlist simple theme I want to have a break tag after each label tag so that each checkbox and its label will be on their own line. To create a custom theme I copied all the code in checkboxlist.ftl. I created a new checkboxlist.ftl file in src/main/webapp/template/simple and pasted the copied code into that file. Struts 2 will first look for a tag's template in [web root]/template/[theme] and if it doesn't find the template there it will use the default template that is part of the Struts 2 core jar.

In src/main/webapp/template/simple/checkboxlist.ftl I added a HTML break tag after each label tag. Now when the Struts 2 framework renders the checkboxlist tag it will use the checkboxlist.ftl template that is in src/main/webapp/template/simple and not the one that is in the Struts 2 core jar.

Create Your Own Theme

If you don't want to over-ride the existing simple theme for a Struts 2 tag you can create a completely new theme. In the example application create a folder src/main/webapp/template/KUTheme. Then copy checkboxlist.ftl from the src/main/webapp/template/simple folder to the src/main/webapp/template/KUTheme folder.

Modify checkboxlist.ftl that is in the KUTheme folder to have the changes you want (for example you could add to the label tag: style="color:red" to have the checkbox labels display in red). Change the value of the theme attribute to be theme="KUTheme" for the Struts 2 checkboxlist tag in the jsp. Now when Struts 2 creates the HTML to display the checkboxlist tag it will use the template that is in the KUTheme folder.

So if you need to use both the default and a custom template for displaying a Struts 2 tag you could create your own folder under src/main/webapp/template, put the modified template file for the tag in that folder and use that folder name as the value for the theme attribute for that Struts 2 tag.


Struts 2 provides default themes that control how the Struts 2 user interface tags are displayed. You can over-ride each tag's theme by creating a new template for that tag and placing that template file in [web root]/template/[theme].

For more information on the Struts 2 themes and creating your own custom theme consult the references below.


  1. Struts 2 CheckBoxList Tag - and
  2. Extending Struts 2 Themes - and
  3. Struts 2 In Action, Donald Brown, Manning, - Chapter 13

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)
BlogCFC was created by Raymond Camden. This blog is running version Contact Blog Owner