JSP Custom Tags

What are Custom Tags?

Custom tags allow you to extend JSP with your own reusable tag libraries, keeping Java code out of JSP pages. A custom tag library consists of:

Tag Handler Class — Java class implementing the tag's behavior (implements SimpleTag or extends SimpleTagSupport)
TLD File — Tag Library Descriptor (XML file) that maps tag names to handler classes
JSP Usage — Import the TLD with taglib directive and use the tag

SimpleTag Handler and TLD File

package com.example.tags;

import javax.servlet.jsp.tagext.SimpleTagSupport;
import javax.servlet.jsp.JspWriter;
import java.io.IOException;

// Tag handler: extends SimpleTagSupport (easiest approach)
public class HelloTag extends SimpleTagSupport {

    // Tag attribute: set via setter
    private String name;

    public void setName(String name) {
        this.name = name;
    }

    // doTag() is called when the tag is encountered in JSP
    @Override
    public void doTag() throws javax.servlet.jsp.JspException, IOException {
        JspWriter out = getJspContext().getOut();
        out.println("<div class='greeting'>");
        out.println("  Hello, <strong>" + (name != null ? name : "World") + "</strong>!");
        out.println("</div>");
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<!-- WEB-INF/mytags.tld -->
<taglib xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd"
        version="2.1">

    <tlib-version>1.0</tlib-version>
    <short-name>mytags</short-name>
    <uri>http://example.com/mytags</uri>

    <tag>
        <name>hello</name>
        <tag-class>com.example.tags.HelloTag</tag-class>
        <body-content>empty</body-content>
        <attribute>
            <name>name</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
        </attribute>
    </tag>

</taglib>

Tag with Body Content

Tags can also process body content — the text or markup between the opening and closing tag. Use getJspBody().invoke(null) to render the body to the response, or capture it with a StringWriter.

Tag with Body and Attributes

package com.example.tags;

import javax.servlet.jsp.tagext.SimpleTagSupport;
import javax.servlet.jsp.JspWriter;
import java.io.*;

// Tag that wraps body content in a styled box
public class BoxTag extends SimpleTagSupport {

    private String title;
    private String color = "#3498db"; // default color

    public void setTitle(String title) { this.title = title; }
    public void setColor(String color) { this.color = color; }

    @Override
    public void doTag() throws javax.servlet.jsp.JspException, IOException {
        // Capture body content into a StringWriter
        StringWriter sw = new StringWriter();
        getJspBody().invoke(sw);
        String bodyContent = sw.toString();

        JspWriter out = getJspContext().getOut();
        out.println("<div style='border:2px solid " + color + ";"
                  + "border-radius:8px;padding:16px;margin:10px 0;'>");
        if (title != null) {
            out.println("  <h4 style='color:" + color + ";margin-top:0;'>"
                      + title + "</h4>");
        }
        out.println("  " + bodyContent);
        out.println("</div>");
    }
}

<tag>
    <name>box</name>
    <tag-class>com.example.tags.BoxTag</tag-class>
    <body-content>scriptless</body-content>
    <attribute>
        <name>title</name>
        <required>false</required>
        <rtexprvalue>true</rtexprvalue>
    </attribute>
    <attribute>
        <name>color</name>
        <required>false</required>
        <rtexprvalue>true</rtexprvalue>
    </attribute>
</tag>

Using Custom Tags in JSP

Using Custom Tags in a JSP Page

<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<%-- Import the custom tag library using the URI defined in the TLD --%>
<%@ taglib uri="http://example.com/mytags" prefix="my" %>
<!DOCTYPE html>
<html>
<head><title>Custom Tags Demo</title></head>
<body>
    <h2>Custom Tag Examples</h2>

    <%-- Simple tag with attribute --%>
    <my:hello name="Alice" />
    <my:hello name="${param.username}" />

    <%-- Tag with body content --%>
    <my:box title="Important Notice" color="#e74c3c">
        <p>This is the body content of the box tag.</p>
        <p>It can contain any HTML markup.</p>
    </my:box>

    <my:box title="Info" color="#2ecc71">
        <p>Green info box with custom title.</p>
    </my:box>

    <%-- Tag without optional attributes (uses defaults) --%>
    <my:hello />
</body>
</html>

Previous Next

JSP Custom Tags

What are Custom Tags?

Tag with Body Content

Using Custom Tags in JSP

Ready to Level Up Your Skills?