JSF - Creating a Custom Converter Tag

[Updated: Sep 10, 2017, Created: Sep 10, 2017]

This tutorial demonstrates how to create a custom converter tag. With the custom tag, we can specify attributes as well which will map to the converter class properties.


The Converter

public class PhoneConverter implements Converter {
  private String format;

  public Object getAsObject(FacesContext context, UIComponent component, String value) {
      Phone phone = PhoneFormat.parse(format, value);
      return phone;

  public String getAsString(FacesContext context, UIComponent component, Object value) {
      Phone phone = (Phone) value;
      return PhoneFormat.format(format, phone);

  public String getFormat() {
      return format;

  public void setFormat(String format) {
      this.format = format;
public enum PhoneFormat {
  STANDARD("(\\d{3})-(\\d{3})-(\\d{4})") {
      String format(Phone phone) {
          return phone.getAreaCode() +
                  "-" + phone.getExchangeCode() +
                  "-" + phone.getLineNumber();
  PLAIN("(\\d{3})(\\d{3})(\\d{4})") {
      String format(Phone phone) {
          return phone.getAreaCode() +
                  phone.getExchangeCode() +

  private final Pattern compiledPattern;

  PhoneFormat(String pattern) {
      compiledPattern = Pattern.compile(pattern);

  public static PhoneFormat getPhoneFormat(String formatString) {
      try {
          return valueOf(formatString.toUpperCase());
      } catch (IllegalArgumentException | NullPointerException e) {
          //returning default format;
          return STANDARD;

  public static Phone parse(String formatString, String value) {
      PhoneFormat phoneFormat = getPhoneFormat(formatString);
      Matcher matcher = phoneFormat.compiledPattern.matcher(value);
      if (!matcher.matches()) {
          throw new RuntimeException(
                  String.format("invalid input: %s. The valid format is of type %s%n",
                          value, phoneFormat.compiledPattern.pattern()));
      String areaCode =;
      String exchange =;
      String line =;
      return new Phone(areaCode, exchange, line);

  public static String format(String formatString, Phone phone) {
      PhoneFormat phoneFormat = getPhoneFormat(formatString);
      return phoneFormat.format(phone);

  abstract String format(Phone phone);
public class Phone {
  private String areaCode;
  private String exchangeCode;
  private String lineNumber;

Creating the custom tag


<?xml version="1.0" encoding="UTF-8"?>


Registering the tag


<web-app xmlns=""
                   " version="3.1">



JSF page


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns=""
    <h2>JSF custom converter example</h2>
        <h:panelGrid columns="2">

            <h:outputLabel for="wph" value="Work Phone: "/>
            <h:inputText id="wph" value="#{phoneBean.workPhone}">
                <u:phoneConverter format="standard"/>

            <h:outputLabel for="cph" value="Cell Phone: "/>
            <h:inputText id="cph" value="#{phoneBean.cellPhone}">
                <u:phoneConverter format="plain"/>

            <h:commandButton value="Submit" action="result.xhtml"/>
            work Phone:
            <h:outputText value = "#{phoneBean.workPhone}">
                <!--the default format will be used-->
                <u:phoneConverter />
            Cell Phone:
            <!--no formatting will be used-->
            <h:outputText value = "#{phoneBean.cellPhone}"/>

Managed Bean

public class PhoneBean {
  private Phone workPhone;
  private Phone cellPhone;

  public Phone getWorkPhone() {
      return workPhone;

  public void setWorkPhone(Phone phone) {
      this.workPhone = phone;

  public Phone getCellPhone() {
      return cellPhone;

  public void setCellPhone(Phone cellPhone) {
      this.cellPhone = cellPhone;

To try examples, run embedded tomcat (configured in pom.xml of example project below):

mvn tomcat7:run-war


On entering and submitting valid phone numbers:

Example Project

Dependencies and Technologies Used:

  • jsf-api 2.2.14: This is the master POM file for Oracle's Implementation of the JSF 2.2 Specification.
  • jsf-impl 2.2.14: This is the master POM file for Oracle's Implementation of the JSF 2.2 Specification.
  • JDK 1.8
  • Maven 3.3.9

JSF Custom Converter Tag Example Select All Download
  • custom-converter-tag
    • src
      • main
        • java
          • com
            • logicbig
              • example
        • webapp
          • WEB-INF

See Also