Getting More from Oracle APEX with HTML Expressions

When building applications with Oracle APEX, one of the biggest strengths is how quickly you can get a working product on screen. However, sometimes the default look and feel isn't enough — you want your data to be more visual, dynamic, or interactive, without diving into complex JavaScript or SQL changes.

One feature that can help with this is the HTML Expression. It's available on many APEX components, like Classic Reports, Interactive Reports, Cards, and Lists, and allows you to format output using simple HTML and template directives. In this blog, I'll share some techniques and real-world examples I regularly use to get more out of HTML Expressions in Oracle APEX.

What Is an HTML Expression?

In Oracle APEX, an HTML Expression is a feature that lets you control how a column's data is displayed using HTML. Instead of just showing raw values, you can wrap them in tags, add classes, tooltips, icons, or even build links, all without changing your underlying SQL or writing extra PL/SQL code.

You'll find the HTML Expression field in many APEX components, including:

• Classic Reports
• Interactive Reports
• Interactive Grids
• Cards
• List Views
• Faceted Search Regions

The key idea is that you write a small HTML snippet and insert values using template directives — placeholders like #COLUMN_NAME# that APEX replaces with the actual values from each row at runtime.

Here's a simple example:

<strong>#EMPLOYEE_NAME#</strong> – #DEPARTMENT#

This would display each employee's name in bold, followed by their department. It's a small change, but it makes your UI clearer and more user-friendly, and it only takes a few seconds to set up.

Useful Template Directives

HTML Expressions aren't just about inserting column values with #COLUMN_NAME#. APEX's Universal Theme also supports a set of template directives, which let you conditionally show content, loop over values, apply templates, and more — all within your HTML Expression. These are incredibly useful for building dynamic UI logic directly in the expression field.

Simple Token Replacement

This is the most common one — just insert the value of a column or item:

<strong>#EMPLOYEE_NAME#</strong>

If Directives

Conditional logic inside your HTML. Useful for displaying badges, icons, labels, or styling based on data.

Syntax:

{if STATUS/}
    Active
{elseif !STATUS/}
    Inactive
{else/}
    Unknown
{endif/}

Evaluation Rules:

Token Modifiers: (from Universal Theme documentation)

Case Directives

Great for checking values explicitly and changing the output accordingly.

Syntax:

{case STATUS/}
    {when ACTIVE/}
        <span class="badge badge-success">Active</span>
    {when INACTIVE/}
        <span class="badge badge-secondary">Inactive</span>
    {otherwise/}
        <span class="badge badge-light">Unknown</span>
{endcase/}

Loop Directives

Used when a column contains a delimited list of values (like A:B:C) and you want to repeat formatting for each one.

Syntax:

{loop ":" TAGS/}
    <span class="tag">&APEX$ITEM.</span>
{endloop/}

This outputs a span for each value in TAGS.

With & Apply Directives

The with and apply directives allow you to apply a reusable template inside your HTML Expression, based on either custom templates or built-in Universal Theme components.

Syntax:

    {with/}
        ...
    {apply TEMPLATE/}

You use {with/} to define any values or context needed, and {apply/} to specify which template to apply.

Built-in Theme Components

Oracle APEX provides several pre-built templates you can use right away with apply. These include:

• Button – {apply THEME$BUTTON/}
• Avatar – {apply THEME$AVATAR/}
• Badge – {apply THEME$BADGE/}
• Comments – {apply THEME$COMMENTS/}
• Content Row – {apply THEME$CONTENT_ROW/}
• Media List – {apply THEME$MEDIA_LIST/}
• Timeline – {apply THEME$TIMELINE/}

You can insert these components dynamically within your region by applying the template inside your HTML Expression.

Example:

    {with/}
        TYPE:=IMAGE
        IMAGE:=#PROFILE_IMAGE#
        IMAGE_ALT:=Profile Image
        SIZE:=t-Avatar--lg
        SHAPE:=t-Avatar--circle
        CSS_CLASSES:=u-color-29
    {apply THEME$AVATAR/}

Depending on what values you pass in context (like label, colour, size), APEX will generate the correct HTML output for that theme component.

Tip:

You can combine with and apply with token substitutions to pass specific values (like label text, icon class, etc.) to make your dynamic content even smarter.

Real-World Examples

Now that we've covered the key directives and syntax, here are a few real-world examples I use regularly in Oracle APEX projects. These small enhancements make a big difference in how data is presented, especially in reports, cards, and dashboards.

Display a Tooltip

Tooltips are a quick way to show additional detail without cluttering the UI. For example, if you have a short label but want to expose a full description on hover:

<span title="#FULL_DESCRIPTION#">#SHORT_LABEL#</span>

This works especially well in tables or card regions where space is limited.

Colour Coding with Badges

You can make statuses or categories easier to scan visually by applying dynamic colours using a badge component.

{with/}
    LABEL:=Overdue
    VALUE:=#AMOUNT_OVERDUE#
    STATE:={if AMOUNT_OVERDUE/}danger{else/}success{endif/}
    STYLE:=t-full-width
{apply THEME$BADGE/}

In the example above, we use with and apply to add a badge. Then, we perform a token replacement for the value and use an if statement to determine the state of the button. This allows us to display either a red or green button, depending on the success and danger colours defined in the theme.

Loop Badges (Perfect for LISTAGG Columns and Multi-Select Values)

If you're using LISTAGG in your SQL query, or have multiple values stored in a delimited string (for example, from a Select Many item or a Popup LOV), you'll know that trying to display them neatly in a report can be tricky.

The common approach is to create a simple comma-separated list like:

Example 1, Example 2, Example 3

This works for short lists, but it quickly becomes hard to read when there are many values or the entries are longer.

A good workaround many developers use is to loop over the values and display each one inside a <li> element, making it more structured. However, if you want to make it even more visual (and space-efficient), I highly recommend wrapping each value in a badge instead.

Here's a sample HTML Expression using the loop directive and APEX's badge styling:

{loop ":" COURSE_LEVEL/}
    <span class="t-Badge" role="status" aria-label="&APEX$ITEM." title="&APEX$ITEM.">
        <span class="t-Badge-value">&APEX$ITEM.</span>
    </span>
{endloop/}

This will split the delimited string (using : in this case) and render each value inside its own badge, making the report far cleaner and easier to scan.

Pro Tips

Once you get comfortable using HTML Expressions, you can start combining techniques to build more dynamic and polished interfaces. Here are a few tips that have helped me get the most out of them in real-world APEX apps:

Style with SQL

Instead of hardcoding styles into the HTML Expression, consider returning CSS classes directly from your SQL query. For example, a STATUS_CLASS column could return values like badge-success, badge-warning, or badge-danger, which your HTML Expression can then use:

<span class="badge #STATUS_CLASS#">#STATUS_LABEL#</span>

This makes it easier to manage styling logic in one place and adapt to future design changes without editing the HTML.

Use Dynamic Icons

If each row should display a different icon — maybe based on type, role, or priority — include the icon class in your SQL result, and reference it in your expression:

<i class="#ICON_CLASS#"></i> #LABEL#

Combine Directives for Smart Display

There's no rule saying you can only use one directive. Mix if, case, and loop blocks to create expressions that adapt based on your data. For example, show a badge only if a column exists, or display different icon/badge combinations using case.

Take It Further with Custom Templates and Plugins

Once you're confident using APEX's built-in template syntax, you can explore how to create your own reusable template components or even build custom plugins. These allow you to encapsulate your UI logic, reuse it across pages, apps, or projects, and share it with your team or the wider APEX community.

The more fluent you become with the template syntax, the more powerful (and cleaner) your UI will be — all while staying declarative and maintainable.

Conclusion

HTML Expressions in Oracle APEX are one of those small features that can make a huge difference. With just a little bit of template syntax knowledge, you can transform the way your data is displayed — adding colour, structure, and interactivity without writing extra code.

By learning to use directives like {if}, {case}, {loop}, and {apply}, and combining them with dynamic data from your SQL queries, you can create much more engaging and readable applications. As you get more comfortable, you'll also open the door to building your own reusable templates and components, taking your APEX development even further.

For more information, check out our Oracle APEX Services, and if you liked this blog, check out our other APEX blogs here.

Contact us today, and one of our expert developers will be in touch.