Basic Examples

Includes

<esi:include src="/_fragments/basic-examples/include" />

The most common ESI tag you're likely to use, Edge will request the given URL and replace the tag with whatever is returned.
The $(varname) syntax can used within the src attribute to use ESI variables

Contrary to the ESI Spec the alt and onerror attributes are not supported.

Examples

<esi:include src="/_fragments/basic-examples/include" />

This page is: https://esi-demo.staging.squiz.co.uk/_fragments/basic-examples/include

Generated at:  Thu, 03 Apr 2025 07:08:17 +0100 - 1015728515

<esi:include src="/_fragments/basic-examples/include2?$(QUERY_STRING)" />

Query string on this page is:

<esi:include src="/_fragments/basic-examples/include2?foo_says_what=$(QUERY_STRING{foo})" />

Query string on this page is: foo_says_what=

<esi:include src="/_fragments/basic-examples/include2?cookie=$(HTTP_COOKIE{SQ_SYSTEM_SESSION})" />

Query string on this page is: cookie=

Vars

<esi:vars>$(QUERY_STRING)</esi:vars>

Another fairly common tag, prints a variable from the ESI into the page.
HTTP_COOKIE and QUERY_STRING variables can be accessed with a dictionary syntax using curly brackets (try adding a ?foo=bar style query string to this page)

Examples

<esi:vars>$(QUERY_STRING)</esi:vars>

<esi:vars>$(QUERY_STRING{foo})</esi:vars>

<esi:vars>$(GEOIP_COUNTRY_CODE)</esi:vars>

US

GeoIP Vars

<esi:vars>$(GEOIP_COUNTRY_CODE)</esi:vars>

All the variables provided by the nginx GeoIP module are available in the ESI scope by default.
They are prefixed with GEOIP_ and all upper case.

Examples

<ul>
<esi:vars>
    <li>continent_code: $(GEOIP_CONTINENT_CODE)</li>
    <li>country_code: $(GEOIP_COUNTRY_CODE)</li>
    <li>country_code3: $(GEOIP_COUNTRY_CODE3)</li>
    <li>country_name: $(GEOIP_COUNTRY_NAME)</li>
    <li>dma_code: $(GEOIP_DMA_CODE)</li>
    <li>latitude: $(GEOIP_LATITUDE)</li>
    <li>longitude: $(GEOIP_LONGITUDE)</li>
    <li>region: $(GEOIP_REGION)</li>
    <li>region_name: $(GEOIP_REGION_NAME)</li>
    <li>city: $(GEOIP_CITY)</li>
    <li>postal_code<: $(GEOIP_POSTALCODE)</li>
</esi:vars>
</ul>

  • continent_code: NA
  • country_code: US
  • country_code3:
  • country_name:
  • dma_code: 535
  • latitude: 39.96250
  • longitude: -83.00610
  • region: Ohio
  • region_name:
  • city: Columbus
  • postal_code: 43215

When - Choose - Otherwise

<esi:choose>
    <esi:when test="condition">
        do something
    </esi:when>
    <esi:otherwise>
        so something else
    </esi:otherwise>
</esi:when>

Simple conditional logic
Content inside when / otherwise tags can include other esi tags

Examples

Hello
<esi:choose>
    <esi:when test="$(QUERY_STRING{name}) == ''">
        Anonymous
    </esi:when>
    <esi:when test="$(QUERY_STRING{name}) == 'barry'">
        Bazza
    </esi:when>
    <esi:otherwise>
        <esi:vars>$(QUERY_STRING{name})</esi:vars>
    </esi:otherwise>
</esi:choose>

Hello Anonymous 

<esi:choose>
    <esi:when test="$(GEOIP_COUNTRY_CODE) == 'AU'">
        G'day mate!
    </esi:when>
    <esi:otherwise>
        Hello!
    </esi:otherwise>
</esi:choose>

Hello!

Remove

<esi:remove> Some content to hide! </esi:remove>

ESI Remove tags and everything they contain are deleted from the processed markup.
Typically used to provide fallback content in case ESI processing fails

Examples

<esi:include src="/_fragments/basic-examples/include"/>
<esi:remove>
  You can't see me!
</esi:remove>

This page is: https://esi-demo.staging.squiz.co.uk/_fragments/basic-examples/include

Generated at:  Thu, 03 Apr 2025 07:08:17 +0100 - 2043420899

HTML Comments

<--esi <esi:vars>$(QUERY_STRING)</esi:vars> -->

A special form of HTML comment tag, the tags are removed by the ESI processor but unlike the <esi:remove> tag ESI instructions within these comments are still processed.

Combine with <esi:remove> to provide fallback content while commenting out ESI tags if ESI process is disabled

Examples

<--esi <esi:include src="/_fragments/basic-examples/include" /> -->

This page is: https://esi-demo.staging.squiz.co.uk/_fragments/basic-examples/include

Generated at:  Thu, 03 Apr 2025 07:08:17 +0100 - 1043742724

Comments

<esi:comment text="comment" />

Tags in this form are removed and never show in the final HTML
They can be used similarly to Matrix comments (<!--@@ Comment goes here @@-->)