Available since OmniFaces 1.0

The <o:converter> is a taghandler that extends the standard <f:converter> tag family with support for deferred value expressions in all attributes. In other words, the converter attributes are not evaluated anymore on a per view build time basis, but just on every access like as with UI components and bean properties. This has among others the advantage that they can be evaluated on a per-iteration basis inside an iterating component, and that they can be set on a custom converter without needing to explicitly register it in a tagfile.


When you specify for example the standard <f:convertDateTime> by converterId="jakarta.faces.DateTime", then you'll be able to use all its attributes such as pattern and locale as per its documentation, but then with the possibility to supply deferred value expressions.

<o:converter converterId="jakarta.faces.DateTime" pattern="#{item.pattern}" locale="#{item.locale}" />

The converter ID of all standard Faces converters can be found in their javadocs. First go to the javadoc of the class of interest, then go to CONVERTER_ID in its field summary and finally click the Constant Field Values link to see the value.

JSF 2.3 compatibility

The <o:converter> is currently not compatible with converters which are managed via the managed=true attribute set on the FacesConverter annotation, at least not when using Mojarra. Internally, the converters are wrapped in another instance which doesn't have the needed setter methods specified. In order to get them to work with <o:converter>, the managed=true attribute needs to be removed, so that OmniFaces ConverterManager will automatically manage them.


In the below demo, it was the intent to use <f:convertDateTime> as follows:

 <f:convertDateTime type="localDateTime" dateStyle="full" timeStyle="full" locale="#{locale}" />

But this wouldn't even run, it will throw the following exception because the #{locale} isn't available during view build time (for a background explanation, check this Stack Overflow answer).

jakarta.faces.view.facelets.TagAttributeException: /showcase/taghandlers/converter.xhtml @53,101 locale="" Attribute did not evaluate to a String or Locale: null
    at com.sun.jsf-impl@4.0.0.SP01//com.sun.faces.facelets.tag.faces.ComponentSupport.getLocale(ComponentSupport.java:423)
    at com.sun.jsf-impl@4.0.0.SP01//com.sun.faces.facelets.tag.faces.core.ConvertDateTimeHandler.setAttributes(ConvertDateTimeHandler.java:89)
    at com.sun.jsf-impl@4.0.0.SP01//com.sun.faces.facelets.tag.faces.ConverterTagHandlerDelegateImpl.applyAttachedObject(ConverterTagHandlerDelegateImpl.java:117)

It works as intuitively expected with the <o:converter> as it allows a render time evaluation of attributes.

For another related use case, checkout the <o:validator> showcase page.

Language Full date time pattern
English Tuesday, March 21, 2023 at 3:50:40 PM Central European Standard Time
Spanish martes, 21 de marzo de 2023, 15:50:40 (hora estándar de Europa central)
French mardi 21 mars 2023 à 15:50:40 heure normale d’Europe centrale
German Dienstag, 21. März 2023 um 15:50:40 Mitteleuropäische Normalzeit
Dutch dinsdag 21 maart 2023 om 15:50:40 Midden-Europese standaardtijd
Arabic الثلاثاء، 21 مارس 2023 3:50:40 م توقيت وسط أوروبا الرسمي
Hebrew יום שלישי, 21 במרץ 2023 בשעה 15:50:40 שעון מרכז אירופה (חורף)
Chinese 2023年3月21日星期二 中欧标准时间 下午3:50:40
Demo source code
<h:dataTable value="#{converterBean.locales}" var="locale">
        <f:facet name="header">Language</f:facet>
        <f:facet name="header">Full date time pattern</f:facet>
        <h:outputText value="#{now.zonedDateTime}">
            <o:converter converterId="jakarta.faces.DateTime" type="localDateTime" dateStyle="full" timeStyle="full" locale="#{locale}" />
Documentation & Sources

VDL documentation

API documentation

Java source code