# encode\_uri

Encodes a URI by replacing special characters with their UTF-8 percent-encoded equivalents. Preserves characters that are valid in URIs (like `:`, `/`, `?`, `#`, `&`, `=`).

```liquid
{% assign url = "https://example.com/search?q=hello world&category=shoes" %}
{% log url | encode_uri %}
```

Output:

```
https://example.com/search?q=hello%20world&category=shoes
```

#### Syntax

```liquid
{{ url | encode_uri }}
{{ string | encode_uri }}
```

| Parameter | Description                 |
| --------- | --------------------------- |
| `url`     | The URL or string to encode |

#### Characters Preserved vs Encoded

| Preserved (not encoded) | Encoded               |
| ----------------------- | --------------------- |
| `A-Z a-z 0-9`           | Spaces → `%20`        |
| `- _ . ! ~ * ' ( )`     | `"` → `%22`           |
| `; , / ? : @ & = + $ #` | `<` `>` → `%3C` `%3E` |
|                         | `{` `}` → `%7B` `%7D` |
|                         | Non-ASCII → `%XX`     |

#### Examples

**Encode URL with spaces:**

```liquid
{% assign product_name = "Blue Running Shoes" %}
{% assign search_url = "https://store.com/search?q=" | append: product_name | encode_uri %}

{% log search_url %}
```

Output:

```
https://store.com/search?q=Blue%20Running%20Shoes
```

**Build API URL with parameters:**

```liquid
{% assign base_url = "https://api.example.com/products" %}
{% assign query = "summer collection 2024" %}
{% assign full_url = base_url | append: "?search=" | append: query | encode_uri %}

{% http url: full_url as response %}
```

**Encode redirect URL:**

```liquid
{% assign return_url = shop.url | append: "/pages/thank-you?order=" | append: order.name %}
{% assign encoded_return = return_url | encode_uri %}
{% assign checkout_url = "https://checkout.example.com?return=" | append: encoded_return %}

{% log checkout_url %}
```

**Handle international characters:**

```liquid
{% assign city = "München" %}
{% assign url = "https://store.com/locations/" | append: city | encode_uri %}

{% log url %}
```

Output:

```
https://store.com/locations/M%C3%BCnchen
```

**Encode tracking URL:**

```liquid
{% assign tracking_url = "https://carrier.com/track?id=" | append: fulfillment.tracking_number | append: "&name=" | append: customer.name | encode_uri %}

{% log "Tracking URL: " | append: tracking_url %}
```

**Build webhook callback URL:**

```liquid
{% assign callback_data = order.id | append: "|" | append: order.email %}
{% assign callback_url = "https://myapp.com/webhook?data=" | append: callback_data | encode_uri %}

{% json webhook_payload %}
  {
    "callback_url": "{{ callback_url }}"
  }
{% endjson %}
```

**Encode file path in URL:**

```liquid
{% assign file_name = "Report Q1 2024 (Final).pdf" %}
{% assign download_url = "https://cdn.example.com/files/" | append: file_name | encode_uri %}

{% log download_url %}
```

Output:

```
https://cdn.example.com/files/Report%20Q1%202024%20(Final).pdf
```

**Create mailto link:**

```liquid
{% assign subject = "Order Inquiry: " | append: order.name %}
{% assign body = "Hi, I have a question about my order " | append: order.name %}
{% assign mailto = "mailto:support@store.com?subject=" | append: subject | append: "&body=" | append: body | encode_uri %}

<a href="{{ mailto }}">Contact Support</a>
```

#### encode\_uri vs url\_encode

| Filter       | Use Case               | Encodes                            |
| ------------ | ---------------------- | ---------------------------------- |
| `encode_uri` | Full URLs              | Preserves `: / ? # & =`            |
| `url_encode` | Query parameter values | Encodes everything including `& =` |

**Example difference:**

```liquid
{% assign value = "hello&world=test" %}

{{ value | encode_uri }}
{% comment %} Output: hello&world=test (& and = preserved) {% endcomment %}

{{ value | url_encode }}
{% comment %} Output: hello%26world%3Dtest (& and = encoded) {% endcomment %}
```

**When to use which:**

```liquid
{% comment %} Use encode_uri for complete URLs {% endcomment %}
{% assign full_url = "https://api.com/search?q=hello world" | encode_uri %}

{% comment %} Use url_encode for individual parameter values {% endcomment %}
{% assign param_value = "hello&world" | url_encode %}
{% assign url = "https://api.com/search?q=" | append: param_value %}
```

#### Common Use Cases

| Use Case       | Example                                     |
| -------------- | ------------------------------------------- |
| Search URLs    | \`"/search?q="                              |
| Redirect URLs  | Encode return URLs for OAuth flows          |
| API requests   | Encode URLs with dynamic parameters         |
| Tracking links | Encode customer/order data in URLs          |
| File downloads | Encode file names with spaces/special chars |

#### Notes

* Uses JavaScript's native `encodeURI()` function
* Preserves URI structure characters (`:`, `/`, `?`, `#`, `&`, `=`, etc.)
* For encoding individual query parameter values, consider `url_encode` instead
* Handles UTF-8 characters (international text) correctly
* Safe to call multiple times (already-encoded characters won't be double-encoded)
* See also: `url_encode` for encoding query parameter values