import {
  CodeGroup,
  Col,
  Note,
  Properties,
  Property,
  Row,
} from '@/components/docs/mdx'


export const exampleFile = 'liquid-examples.js'


# Liquid Template Guide

Picture crafting an email template that seamlessly adapts with unique, personalized information. That's what Liquid helps you do. It's like a special recipe book for emails. You write some simple Mad Libs-style phrases, and boom! Your email can show different things to different people. Want to greet visitors by name? Show special deals? Liquid makes it possible. It's not super fancy, but it's pretty neat. Check out the basic Liquid guide below to learn its tricks. 

### The Basics

These essential tags will allow you to personalize your email extensively with links, buttons, images, and even audio to kick things off.

---

## Name Personalization

    Use these to make your emails feel more human, even when subscriber data is incomplete.

    #### First name or fallback
    Simple fallback when first name is missing.
    

    #### First name, else last name, else default
    Cascading fallback logic for better personalization.
    

---
## Confirmation Emails

    Ensure that order confirmations, receipts, and status updates work even if optional fields are missing.

    #### Order confirmation with order ID
    Display order confirmation when order ID exists.
    

    #### Download link for digital products
    Conditional download links for digital product purchases.
    

    #### Trial period days left
    Show remaining trial days with fallback for expired trials.
    
---
## Marketing

    Create subject lines, headlines, and calls-to-action that gracefully fallback when needed.

    #### Friendly subject line
    Personalized subject lines with fallback.
    

    #### Greeting with company name fallback
    Dynamic greetings that adapt to available data.
    

    #### Plan name with default
    Display subscription plan with sensible default.
    

---
    ## Product Recommendations

    Create dynamic product suggestions based on purchase history and preferences with smart fallbacks.

    #### Category-based recommendations
    Show products based on last purchased category.
    

    #### Purchase history fallback
    Recommend based on previous purchases or show general promotions.
    

    #### Seasonal promotion with personalization
    Combine seasonal offers with personal data.
    
---

  
    ## Links

    Links are among the most common elements used. They are simple, accessible to users, and very recognizable for their functionality. The liquid tag consists of two parts: a URL and the label. Users familiar with HTML will recognize the components of an HTML `<a href>` (anchor) tag.

    ### Required Attributes
    
      - **url** (`Url string`): 
        Url you want the user to go to when they interact with the link.
      
      - **hyperlink** (`Label Text`): 
        The text you want visible for the user to interact with.
      
    

    
> A common gotcha we see is users including a full HTML `<a href>` tag, which causes the link to not work. For example a user will use <br/> `<a href="https://example.com"></a>` when they only need to use the `https://example.com`


  
  
    
    

    ### Preview<br/><br/> <a href={'https://example.com'}>Click Here!</a>

  

---

  
    ## Button

    Buttons offer the same functionality as links but come with a distinct, button-like appearance. They are perfect for Call to Actions, making them stand out more effectively than standard links within text.

    Their syntax is the same as links, and follows the same rules, avoid using html inside for the link.

    
      - **url** (`Url string`): 
        Url you want the user to go to when they interact with the link.
      
      - **hyperlink** (`Label Text`): 
        The text you want visible for the user to interact with.
      
      - **color** (`hexcode`): 
        HEX code color for the button. You can read more about [hex code colors here](https://htmlcolorcodes.com/tutorials/html-link-color/). Or find some great colors [here](https://uicolors.app/create).
      
    

  
  
    
    

    ### Preview<br/><br/> <button type="button" className="rounded bg-white px-2 py-1 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300">Click here!</button>

  

---

  
    ## Audio

    If you want to link to some audio for your users to enjoy, and their email client supports playback inside the client, there's a tag for that! It also includes a direct link to the audio for clients that don't support playback.

    
      - **url** (`Url string`): 
        Public url to the audio file for users to play.
      
      - **type** (`string`): 
        Defines this link is an audio file for playback.
      
    

  
  
    
    

       ### Preview<br/><br/> <audio controls src='https://app.bentonow.com/sounds/click.mp3'>If your email client does not support playing audio <a href='https://app.bentonow.com/sounds/click.mp3'>click here to listen.</a><source src='https://app.bentonow.com/sounds/click.mp3'></source></audio>

    If your email client does not support playing audio <a href='https://app.bentonow.com/sounds/click.mp3'>click here to listen.</a>

  

---

  
    ## Images

    Images are worth a thousand words and play an essential visual role in any message, enhancing engagement and comprehension. This versatile image tag supports all HTML versions and options, ensuring compatibility across various platforms. Whether for informative content or captivating visuals, it seamlessly integrates to elevate your web presence.

    
      - **url** (`Url string`): 
        Public url to the image file to display.
      
      - **image_tag** (`string`): 
        comma separated list of options, supports in order `css classes`, `id tag`, `alternate text`, `width in pixels`, `height in pixels`
      
    

  
  
    
    

    ### Preview<br/><br/> <img src="https://app.bentonow.com/brand/bento-logo-3d.png" className="class name" id="id" alt="alt" width="100" height="200" />

  

---

  
    ## Greeting

    Constructs a personalized greeting for the email recipient, formatted with a preference for using their first name, creating a warm and engaging tone that fosters a sense of familiarity and connection right from the start.

    
> Liquid Tags like this only return the plain text, inheriting styling from the surrounding copy. This ensures a consistent and cohesive appearance with the rest of your template.


  
  
    
    

    ### Preview<br/><br/> Hi Jesse,

  

---

  
    ### Formatted Name

    Constructs their full name from the name fields provided.

    
> Liquid Tags like this only return the plain text, inheriting styling from the surrounding copy. This ensures a consistent and cohesive appearance with the rest of your template.


  
  
    
    

    ### Preview<br/><br/> John Doe

  

---

  
    ### Gravatar Avatar

    This feature uses the user's email to show their Gravatar Avatar, ensuring a consistent and recognizable online presence. You can learn more about [Gravatar Avatars here](https://gravatar.com).

    
> In the case that the user does not have a Gravatar avatar a fallback image is provided.


  
  
    
    

    ### Preview<br/> <span className=''><img src="https://gravatar.com/avatar/740cc1919c09dfe40a11772accd61ed1.png?d=mp" alt="bento_docs_feedback@bentonow.com" className='inline-block  h-5 align-middle' /> John</span>

  


### Operators & Conditionals


  
    ### If Conditional

    This is a fantastic way to showcase content based on subscriber tags. For instance, you can display a thank you message for subscribers who have completed a purchase. But if they have not, they won't get the thank you.

    
> You can check any element in an if conditional, can be tags, subscribers city, any tag or field you have created. By default the additional content will not display. <br/><br/>You are not limited to what content can be inside the conditional. <br/>They can be [text links](/docs/liquid_guide#links), [buttons](/docs/liquid_guide#button), [images](/docs/liquid_guide#images) or full parts of your template.


  
  
    
    

    ### Preview<br/> This visitor has a 'customer' tag.

  

---

  
    ### If/Else Conditional

    Once more, this is an excellent method to display content tailored to subscriber tags. Continuing with our example, if they haven't made a purchase, rather than expressing gratitude, you can utilize else to include a CTA encouraging them to buy.

    
> You can check any element in an if conditional, can be tags, subscribers city, any tag or field you have created. <br/><br/>You are not limited to what content can be inside the conditional. <br/>They can be [text links](/docs/liquid_guide#links), [buttons](/docs/liquid_guide#button), [images](/docs/liquid_guide#images) or full parts of your template.


  
  
    
    

    ### Preview<br/> You are in Sydney!

  

---

  
    ### Operators

    These options enable math and comparison operations. For instance, if you want to offer a discount to subscribers with more than 10 orders or who have spent over $100, you can use an operator to achieve this.

    
> Math can be performed on any numeric field, but for non-numeric fields, you will need to use count. <br/><br/>You are not limited to what content can be inside the conditional. <br/>They can be [text links](/docs/liquid_guide#links), [buttons](/docs/liquid_guide#button), [images](/docs/liquid_guide#images) or full parts of your template.


  
  
    
    

    ### Preview<br/> This visitor has ordered over 10 times!

  


## Visitors Reference

| Liquid Tag                                                                                                            | Result                 |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------- |
|                                | test@example.com       |
|          | bento confirmation url |
|                                    |                        |
|            | users unsubscribe url  |
|  |                        |
|                      |                        |
|                      | control                |
|                                  | Sydney                 |
|                            | Australia              |
|                              | `true`/`false`         |
|                    |                        |
|                                  | Subscriber tags        |
|                              | Male                   |
|                                  |                        |
|                          |                        |
|                      | John                   |
|                        | Doe                    |

## Liquid Filters

Liquid filters are powerful keywords that instruct Liquid how to manipulate the variables we provide. They are commonly used for tasks such as appending text, rounding numbers, performing basic math operations, formatting data, and sorting lists. These filters go beyond mere inactive template filling; they actively transform and refine the input to produce dynamic, polished outputs. For instance, you can use filters to truncate lengthy descriptions, convert strings to uppercase, or even handle complex date manipulations. By leveraging these versatile tools, developers can create more responsive and interactive web experiences. Ultimately, Liquid filters are essential for anyone looking to maximize the functionality and presentation of their templated content, ensuring that the final output is both accurate and aesthetically pleasing. Below is a list of filters, but you can find the full specification [documentation here](https://shopify.github.io/liquid/).


### Append

<div id="append" className={'scroll-mt-44'}>
  Adds the specified string to the end of another string.
</div>


<br />
### Capitalize

<div id="capitalize" className={'scroll-mt-44'}>
  Makes the first character of a string capitalized and converts the remaining
  characters to lowercase.
</div>


<br />
### Default

<div id="default" className={'scroll-mt-44'}>
  Sets a default value for any variable with no assigned value. default will
  show its value if the input is `nil`, `false`, or `empty`.
</div>


<br />
### Divide By

<div id="divide_by" className={'scroll-mt-44'}>
  Divides a number by another number.
  <br />
  The result is rounded down to the nearest integer (that is, the floor) if the
  divisor is an integer.
</div>


<br />

### Downcase

<div id="downcase" className={'scroll-mt-44'}>
  Makes each character in a string lowercase. It has no effect on strings which
  are already all lowercase.
</div>


<br />

### Minus

<div id="minus" className={'scroll-mt-44'}>
  Subtracts a number from another number.
</div>


<br />

### New Line Br

<div id="new_line_br" className={'scroll-mt-44'}>
  Inserts an HTML line break `<br />` in front of each newline `\n` in a string.
</div>


<br />

### Pluralize

<div id="pluralize" className={'scroll-mt-44'}>
  Pluralizes a word based on a count.
</div>


<br />

### Plus

<div id="plus" className={'scroll-mt-44'}>
  Adds a number to another number.
</div>


<br />

### Prepend

<div id="prepend" className={'scroll-mt-44'}>
  Adds the specified string to the beginning of another string.
</div>


<br />

### Remove

<div id="remove" className={'scroll-mt-44'}>
  Removes every occurrence of the specified substring from a string.
</div>


<br />

### Replace

<div id="replace" className={'scroll-mt-44'}>
  Replaces every occurrence of the first argument in a string with the second
  argument.
</div>


<br />

### Round

<div id="round" className={'scroll-mt-44'}>
  Rounds a number to the nearest integer or, if a number is passed as an
  argument, to that number of decimal places.
</div>


<br />

### Truncate

<div id="truncate" className={'scroll-mt-44'}>
  Shortens a string down to the number of characters passed as an argument. If
  the specified number of characters is less than the length of the string, an
  ellipsis (…) is appended to the string and is included in the character count.
</div>


<br />

### Upper

<div id="upper" className={'scroll-mt-44'}>
  Makes each character in a string uppercase. It has no effect on strings which
  are already all uppercase.
</div>


<br />

## Helpers Reference

### Environment Variables

Interact and check the env variables.

| Liquid Tag                                                                         | Result           |
| ---------------------------------------------------------------------------------- | ---------------- |
|             | `true` / `false` |
|              | `true` / `false` |
|  | `true` / `false` |

## Encryption / Hashing

These helpers offer a convenient way to encrypt or hash string values, enabling you to encrypt something for a user on demand without needing to store it for retrieval. Excellent for removing PII out of plain text.

| Liquid Tag                                                                                            | Result                                   |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------- |
|                      | 312f946cb92aaa541723382cda411c31         |
|  | 63fa337d0a0e6520a12e223657d17184a5e2b131 |

### Time

These tools provide an interface to dynamically work with time, which proves invaluable when managing extensive subscriber lists that necessitate batching. By calculating the precise time for each user when the email is queued for sending, you mitigate concerns about information in the template becoming outdated if a batch is sent several hours later. This ensures that all recipients receive the most current and relevant information. This can also be used to remind a user that their birthday is coming up in X number of days, or that it's been X number of weeks since they last signed in or made a purchase.


> All time responses are formatted time strings.


| Liquid Tag                                                                                                                                | Result                    |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
|                                  | 2010-11-01 00:00:00 +0000 |
|                                                      | 116                       |
|                                                     | 16                        |
|                                                     | 87                        |
|                                                      | 614                       |
|                                                     | 2022-12-31 00:00:00 +0000 |
|  | 2010-10-31 00-00-00 -0600 |
|                                                       | 1288483200                |
|                                         | about 2 months            |

### Money

Format money according to the currency assigned to the subscriber or visitor.

| Liquid Tag                                                                 | Result      |
| -------------------------------------------------------------------------- | ----------- |
|  | $900.00 USD |

### Lottery Element

Randomly pick an element from the provided list (lottery-style). No limitations or weighting applied to elements, ensuring each item has an equal chance of selection.


> Supports only strings and you must provide the split delimiter


| Liquid Tag                                                                                                                       | Result  |
| -------------------------------------------------------------------------------------------------------------------------------- | ------- |
|  | Offer 3 |

## Broadcasts

These liquid tags are designed to function specifically within the context of your broadcast and will not work anywhere else.

| Liquid Tag                                                            | Result                               |
| --------------------------------------------------------------------- | ------------------------------------ |
|     | Broadcast Subject                    |
|        | Name of the broadcast                |
|  | Timestamp when broadcast was created |


> The Timestamp returned by created_at can be reformatted using the time
>   helpers, providing you with the flexibility to display the date and time in
>   various formats. Additionally, you can easily adjust the timezone to align
>   with your specific use case needs, whether it's for local time representation
>   or to represent time in the subscriber's local time.


## Sequences

These liquid tags are designed to function specifically within the context of your sequences and will not work anywhere else.


  ### Cancel the sequence

This creates a hyperlink that allows the user to stop the sequence they are in. This is helpful to give subscribers an alternative to unsubscribe. This is used in the Bento signup drip sequence.


{' '}

<CodeSample
  exampleFile={exampleFile}
  exampleKey="sequence_cancel_liquid_code"
/>
<CodeSample
  exampleFile={exampleFile}
  exampleKey="sequence_cancel_html_result"
/>

### Preview<br/> <a href='http://app.bentonow.com/'>No more emails like this!</a>


---


  ### Skip forward to the next email in the Sequence

This feature lets you seamlessly skip forward to the next email in the sequence and offers the option to redirect recipients to a specific web URL.

{' '}


> When redirecting the URL, ensure it matches the domain of the author sending
>   the emails.


{' '}

<CodeSample
  exampleFile={exampleFile}
  exampleKey="sequence_fast_forward_liquid_code"
/>
<CodeSample
  exampleFile={exampleFile}
  exampleKey="sequence_fast_forward_html_result"
/>

### Preview<br/> <a href='http://app.bentonow.com'>Instantly get the next email.</a> <br/> <a href='http://app.bentonow.com&redirect=https://bentonow.com/skip'>Instantly get the next email with redirect.</a>


## Ecommerce


  ### Render Last Cart

This feature enables you to display the user's last cart, perfect for reminder emails to encourage users to complete their purchase.


{' '}

<CodeSample
  exampleFile={exampleFile}
  exampleKey="ecommerce_render_cart_liquid_code"
/>
<CodeSample
  exampleFile={exampleFile}
  exampleKey="ecommerce_render_cart_html_result"
/>

### Preview<br/>

Apple Watch Ultra 2 - 799.00 USD - 1 <br/>
49mm Indigo Alpine Loop - 99.00 USD - 1<br/>
49mm Orange Ocean Band - 99.00 USD - 1<br/>


---


  ### Render Products

This feature allows you to showcase a list of products.

{' '}


> This is available exclusively within flows.


{' '}


> {' '}
>   This functions just like render cart but works seamlessly in flows and can
>   extend beyond the user's most recent cart.


{' '}

<CodeSample
  exampleFile={exampleFile}
  exampleKey="ecommerce_render_products_liquid_code"
/>
<CodeSample
  exampleFile={exampleFile}
  exampleKey="ecommerce_render_products_html_result"
/>

### Preview<br/>

Apple Watch Ultra 2 - 799.00 USD - 1 <br/>
49mm Indigo Alpine Loop - 99.00 USD - 1<br/>
49mm Orange Ocean Band - 99.00 USD - 1<br/>


---
### Abandoned Cart Checkout URL

A quick and convenient method for generating a personalized URL to seamlessly guide users back into their shopping cart from a reminder email. This makes it easier for users to return to their cart.


> This provides the string URL, offering flexibility to create a full HTML
>   hyperlink as needed.


> This is available exclusively within flows.


| Liquid Tag                                                                                                               | Result     |
| ------------------------------------------------------------------------------------------------------------------------ | ---------- |
|  | URL string |

## Stripe and Shopify

These Liquid tags enable you to seamlessly integrate with the [Stripe](https://www.stripe.com) and [Shopify](https://www.shopify.com) platforms, offering convenient methods to generate on-demand coupon codes.


> This only returns a string value of the coupon code.


  ### Shopify coupon

Generate a unique coupon code with Shopify.

{' '}


  - **coupon name** (`string`): 
    Name for the coupon code.
  
  - **discount amount** (`string`): 
    Defines the discount amount.
  
  - **discount type** (`string`): 
    Defines the type of discount valid options: `fixed_amount` `percentage`.
  


{' '}


### Preview<br/>

100OFF


---


  ### Create a distinctive discount code using Stripe

Generate a unique coupon code with Stripe

{' '}


  - **coupon name** (`string`): 
    Name for the coupon code.
  
  - **discount %** (`string`): 
    Defines the discount amount.
  
  - **length** (`string`): 
    In months how long the coupon will be valid.
  


{' '}


### Preview<br/>

TEST


---


  ### Stripe billing portal link

Create a user-specific Stripe payment portal link.

{' '}


> Generates the URL; it does not create a full HTML link.


{' '}


  - **URL** (`string`): 
    Name for the coupon code.
  


{' '}

<CodeSample
  exampleFile={exampleFile}
  exampleKey="stripe_billing_portal_liquid_code"
/>
<CodeSample
  exampleFile={exampleFile}
  exampleKey="stripe_billing_portal_html_result"
/>

### Preview<br/>

https://bentonow.com


## External Data

This feature enables you to seamlessly integrate public data from external sources outside of bento directly into your templates, enhancing the richness and relevance of your content with broader data and context.


  ### RSS | JSON | HTML Parse

You define the url as your data source followed by the type option for how to handle the data. Once you have defined your data you will use a loop to iterate over each item in the returned data.

{' '}


> Generates the string content. Requests must be public, and utilize a{' '}
>    method. <br />
>   Response data will be string data only.


{' '}


  - **URL** (`string`): 
    Name for the coupon code.
  
  - **type** (`string`): 
    Supported data types are `rss` `fetch_json` `youtube` `fetch_html`
  


{' '}


> `fetch_html` has an additional parameter that allows you to define an HTML tag as
>   the parent data wrapper, and what defines the children.


{' '}


### Preview<br/>

Milk<br/>

Eggs<br/>

Bread<br/>


## Gmail Promo

Add Promo Annotation


> Please note that this feature depends on Gmail's discretion.


  ### Promo annotation

{' '}


  - **promo** (`string`): 
    What the promo is, often use the amount.
  
  - **annotation** (`string`): 
    The supporting annotation to the promo, can be the coupon code.
  


{' '}