> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/avante-themes/developer/developer-docs.md).

# Developer docs

This page provides technical documentation for the Avante theme. It is intended for developers, agencies, or individuals with advanced technical knowledge.

{% hint style="warning" %}
**Note:** Only edit your theme's code if you cannot make the necessary changes using a Shopify app or the theme editor. If you want to add custom features but lack experience with HTML, CSS, and JavaScript, [contact us](/docs/services/custom-development-services.md) or consider hiring a Shopify Expert.
{% endhint %}

***

### Theme dependencies

Avante bundles the following third-party libraries:

| Library       | Version | File                         | Used for                                                                                                                                      |
| ------------- | ------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| GSAP TweenMax | 2.1.2   | `assets/TweenMax.min.js`     | Hover image reveal animation in Editorial: Collection list, Editorial: Link list, and Scrolling promotion sections (`HoverImageReveal` class) |
| Masonry       | 4.2.2   | `assets/masonry.pkgd.min.js` | Cascading grid layout in Image grid section, Blog posts, and Page sections (`CascadingGrid` class)                                            |
| Fitty         | —       | `assets/fitty.min.js`        | Text scaling                                                                                                                                  |

{% hint style="danger" %}
Do not load duplicate versions of these libraries from a CDN. If your app depends on GSAP or Masonry, verify the bundled version meets your requirements before adding a second copy — conflicts between instances can cause unpredictable behavior.
{% endhint %}

***

### Theme architecture

The file structure follows the standard Shopify theme file structure.

#### CSS

Avante includes a single `base.css` file containing styles for UI elements shared across the entire theme. All other styles are separated into smaller files — each section or block has its own file. This avoids loading styles for sections that aren't added to a page, improving performance. All CSS is written in-house; no CSS frameworks are used.

#### JavaScript

JavaScript is separated into multiple files. `global.js` contains scripts that can be connected to a template or section multiple times (for example, color swatches in the product card). All other JavaScript is divided into files containing functionality for a specific section.

***

### Adding custom JavaScript and CSS

Avante includes placeholder files for custom code so you can extend the theme without editing its source files.

{% hint style="success" %}
**Best practice:** Always duplicate your theme before editing any code. This gives you a clean backup to restore if anything goes wrong.
{% endhint %}

<figure><img src="/files/IdtrNdliPYuPrSffjsCf" alt=""><figcaption></figcaption></figure>

#### Custom JavaScript

1. Go to **Snippets** and open `custom-assets.liquid`
2. Set `useCustomScript` to `true`
3. Open `assets/custom-script.js` and add your code

<figure><img src="/files/O7gi4SzZ3ZQFdRjVVcLi" alt=""><figcaption></figcaption></figure>

#### Custom CSS

1. Go to **Snippets** and open `custom-assets.liquid`
2. Set `useCustomStyles` to `true`
3. Open `assets/custom-styles.css` and add your code

<figure><img src="/files/nlgglerNxdkAZ49t0yYg" alt=""><figcaption></figcaption></figure>

***

### Custom events

Avante dispatches custom events on the `document` object at key lifecycle moments. Listen to these events to extend theme behavior without modifying theme files.

```js
document.addEventListener('cart:updated', (event) => {
  const cart = event.detail.cart;
  // your code here
});
```

#### Cart events

| Event                     | Payload            | When it fires                                        |
| ------------------------- | ------------------ | ---------------------------------------------------- |
| `cart:updated`            | `{ cart }`         | Cart state changes (item added, removed, or updated) |
| `cart-drawer:open`        | `{ targetTag }`    | Cart drawer opens                                    |
| `ajaxProduct:added`       | `{ product }`      | Product successfully added to cart via AJAX          |
| `ajaxProduct:error`       | `{ errorMessage }` | Add-to-cart AJAX request returns an error            |
| `product_cart:update_url` | —                  | Cart URL is updated after a product action           |

#### Product & variant events

| Event                          | Payload                       | When it fires                                                                     |
| ------------------------------ | ----------------------------- | --------------------------------------------------------------------------------- |
| `variant:change`               | `{ variant }`                 | Active variant changes on a product page, Featured product section, or Quick view |
| `color-swatch:change`          | `{ colorName, firstMediaId }` | Color swatch is selected                                                          |
| `updateVariantMedia`           | —                             | Variant media gallery is updated                                                  |
| `product-recommendations:load` | —                             | Product recommendations section loads                                             |

#### Quick view events

| Event              | Payload   | When it fires                       |
| ------------------ | --------- | ----------------------------------- |
| `quickview:open`   | `{ ... }` | Quick view modal opens              |
| `quickview:close`  | —         | Quick view modal closes             |
| `quickview:loaded` | —         | Quick view content finishes loading |
| `quickview:error`  | —         | Quick view failed to load           |

#### Dialog & modal events

| Event                | Payload | When it fires                        |
| -------------------- | ------- | ------------------------------------ |
| `dialog:after-show`  | —       | Any pop-up or drawer is fully opened |
| `dialog:after-hide`  | —       | Any pop-up or drawer is fully closed |
| `product-modal:open` | —       | Product image modal opens            |
| `searchmodal:close`  | —       | Search modal closes                  |

#### Navigation & filter events

| Event                     | Payload | When it fires                                                                    |
| ------------------------- | ------- | -------------------------------------------------------------------------------- |
| `page:reloaded`           | —       | Collection or search page content is reloaded via AJAX after filters are applied |
| `filters:rerendered`      | —       | Filter UI is rerendered                                                          |
| `collapsible-menu:opened` | —       | Collapsible navigation menu opens                                                |

#### Other events

| Event            | Payload       | When it fires                        |
| ---------------- | ------------- | ------------------------------------ |
| `form:submitted` | `{ formID }`  | A form is submitted                  |
| `image:show`     | `{ mediaId }` | A media item is shown in the gallery |
| `body:visible`   | —             | Page body becomes visible after load |

***

### Adapting content between sidebars

When sidebars are enabled, the main content area adapts to the container width between sidebars — not the browser window width. For example, if a sidebar uses **Main L half screen** and the browser is 1920px wide, the main content renders at mobile width.

Because CSS container queries lack sufficient browser support, Avante calculates the browser window width at which each breakpoint (1440px, 1024px, 768px, 500px) applies.

#### Formula

```
[Browser window width] = [Media query] + [Main sidebar width] + [Secondary sidebar width]
```

#### Sidebar sizes

| Sidebar            | Width              |
| ------------------ | ------------------ |
| Main XS            | 12.5% of viewport  |
| Main S             | 18.75% of viewport |
| Main M             | 25% of viewport    |
| Main L half screen | 50% of viewport    |
| Secondary sidebar  | 96px (fixed)       |

Minimum sidebar width: **280px** (White space: Spacious) / **200px** (White space: Compact).

#### Examples

**Example 1:** Main XS sidebar, White space: Spacious, target breakpoint: 1440px

The sidebar is 12.5% of the browser window width (X), minimum 280px.

```
1440 + 12.5% × X = X
X = 1440 / (1 − 0.125) ≈ 1646px
```

Since 12.5% × 1646 ≈ 206px is less than the 280px minimum, the sidebar is capped at 280px:

**Result: 1440 + 280 = 1720px**

***

**Example 2:** Main M + secondary sidebar, White space: Compact, target breakpoint: 1024px

Main M is 25% of X, minimum 200px. Secondary sidebar is 96px.

```
1024 + 25% × X + 96 = X
X = (1024 + 96) / (1 − 0.25) ≈ 1493px
```

Check: 1493 × 25% ≈ 373px > 200px minimum — calculation is valid.

**Result: 1493px**

***

### Related

* [How to update your Shopify theme](/docs/theme-management/how-to-update-your-shopify-theme.md)
* [Custom development services](/docs/services/custom-development-services.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://staylime.com/docs/avante-themes/developer/developer-docs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.