> 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 Avante developer reference: bundled libraries, CSS and JavaScript structure, custom code files, theme events, and how layouts adapt between sidebars. This page is for developers, agencies, and anyone comfortable with HTML, CSS, and JavaScript. {% hint style="warning" %} Only edit theme code when an app or the theme editor cannot do the job. If you need a custom feature but do not work with code, [contact us](/docs/services/custom-development-services.md) or hire a Shopify Expert. {% endhint %} *** ### **Theme dependencies** Avante bundles these third-party libraries: | Library | Version | File | Used for | | ------------------------------------------------ | ------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Swiper | 11.1.14 | `assets/swiper-bundle.min.js` | Sliders and carousels across the theme. Loaded on every page. | | Masonry | 4.2.2 | `assets/masonry.pkgd.min.js` | Cascading layout in Image grid, Blog post, and Multicolumn (`CascadingGrid`, ``). Loaded on every page. | | GSAP TweenMax | 2.1.2 | `assets/TweenMax.min.js` | Hover image reveal in Collection list with popover image, Link list with popover image, Scrolling promotion, and Quick filter (`HoverImageReveal`, ``). Loaded only when needed. | | Quicklink | — | `assets/quicklink.umd.js` | **Preload links on hover**. Prefetches same-site links visible on screen. Not loaded in the theme editor. | | UI Initiative Stories Slider and Carousel effect | 1.0.0 | `assets/stories-slider.min.js`, `assets/effect-carousel.min.js` | Stories slideshow section only. | {% hint style="danger" %} Do not load a second copy of these libraries from a CDN. If an app needs Swiper, GSAP, or Masonry, check that the bundled version meets its requirements first. Two instances on one page can conflict. {% endhint %} *** ### **Theme architecture** The file structure follows the standard Shopify theme structure. **CSS.** Almost all styles are in `assets/base.css`, loaded on every page. A few files load only where they are needed: RTL styles, customer account pages, policy pages, Swiper, Product bundle, and Stories slideshow. All CSS is written in-house. No CSS framework is used. **JavaScript.** `assets/global.js` holds the shared components: the product form, variant picker, quantity input, drawers and modals, color swatches, infinite scroll, and more. Larger features have their own files and load only where they are used, for example `cart-drawer.js`, `quick-view.js`, `facets.js`, `media-gallery.js`, `predictive-search.js`, `product-bundle.js`, `quick-filter.js`, and `reveal-animation.js`. *** ### **Adding custom JavaScript and CSS** Avante has placeholder files for your own code, so you do not have to edit theme files. {% hint style="success" %} Duplicate the theme before editing code, so you have a clean copy to restore. {% endhint %} {% stepper %} {% step %} **Turn the files on** In **Online Store → Themes → ⋯ → Edit code**, open `snippets/custom-assets.liquid`. Set `useCustomScript` to `true` for JavaScript and `useCustomStyles` to `true` for CSS. {% endstep %} {% step %} **Add your code** Write JavaScript in `assets/custom-script.js` and CSS in `assets/custom-styles.css`. The CSS file loads after `base.css`. The script loads with `defer`. {% endstep %} {% endstepper %} For a few CSS rules, **Theme settings → Custom CSS** in the theme editor works too, with no code editor needed. *** ### **Custom events** Avante dispatches events at key moments. Unless a row says otherwise, the event fires on `document`, and its data is in `event.detail`. ```js document.addEventListener('cart:updated', (event) => { const cart = event.detail.cart; // your code here }); ```
Cart | Event | Detail | When it fires | | ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------ | | `cart:updated` | `{ cart }` | The cart changes: an item is added, removed, or updated. | | `cart-drawer:open` | — | The cart drawer opens. | | `ajaxProduct:added` | `{ product }` | A product is added to the cart via AJAX. | | `ajaxProduct:error` | `{ errorMessage }` | Adding to the cart returns an error. | | `quantity:max-reached` | `{ input, max, changed }` | A quantity input reaches its maximum. Fires on the `` element and bubbles. |
Product and variants | Event | Detail | When it fires | | ------------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `variant:change` | `{ variant }` | The selected variant changes on the product page, in Featured product, or in Quick view. | | `updateVariantMedia` | — | The gallery updates to the selected variant's media. | | `color-swatch:change` | `{ colorName, firstMediaId }` | A color swatch is chosen on a product card. Fires on the card's slider element, not on `document`. `colorName` is `'all'` when the selection is cleared. | | `media-update-by-swatch` | — | A product card swaps its image after a swatch change. Fires on the card and bubbles. | | `product_cart:update_url` | — | A product card's link and Quick view URL change to the selected variant. | | `product-recommendations:load` | — | Product recommendations finish loading. |
Quick view | Event | Detail | When it fires | | ------------------ | ---------------- | ---------------------------------- | | `quickview:open` | `{ productUrl }` | Quick view starts opening. | | `quickview:loaded` | `{ productUrl }` | Quick view content has loaded. | | `quickview:error` | `{ productUrl }` | Quick view content failed to load. | | `quickview:close` | — | Quick view closes. |
Modals, drawers, and media | Event | Detail | When it fires | | --------------------- | ------------------------------- | ------------------------------------------------------------------------------- | | `dialog:after-show` | — | A `` opens. | | `dialog:after-hide` | — | A `` closes. | | `body:visible` | `{ targetTag }` on some drawers | A drawer or modal closes and page scrolling is unlocked. | | `product-modal:open` | `{ mediaId }` | The product media zoom opens. Fires on the gallery slider and does not bubble. | | `product-modal:close` | `{ modal }` | The product media zoom closes. Fires on the gallery slider and does not bubble. | | `image:show` | — | A media item is shown in the zoom modal. | | `searchmodal:close` | — | The search modal closes. |
Collections, navigation, and forms | Event | Detail | When it fires | | ------------------------- | -------------------- | -------------------------------------------------------------------------------------- | | `page:reloaded` | — | Collection or search results reload after filtering, sorting, or a Quick filter click. | | `filters:rerendered` | — | The filter UI is rerendered. | | `infinite-scroll:loaded` | `{ sectionId }` | The next page of products is added by infinite scroll. | | `infinite-scroll:error` | `{ sectionId }` | Loading the next page failed. Fires on the infinite scroll element and bubbles. | | `tabs:content-loaded` | `{ panel, blockId }` | A tab panel loads its content. | | `collapsible-menu:opened` | — | A collapsible menu opens. | | `form:submitted` | `{ formID }` | A form is submitted. Not fired for the Newsletter section. |
*** ### **Layout between sidebars** When the store uses sidebar navigation, the main content area sits between the sidebars, so it is narrower than the browser window. Sections adapt to the width of that area, not the window. With sidebars on, the content wrapper `.inside-content` is a CSS container named `inside-content`. The theme switches section layouts with container queries at 1440px, 1200px, 1024px, 920px, 768px, and 500px. Without sidebars, regular media queries apply. To make your own CSS follow the same layout, write a rule for each case: ```css @media screen and (max-width: 768px) { .my-block { flex-direction: column; } } @container inside-content (max-width: 768px) { .my-block { flex-direction: column; } } ```
Estimate the window width for a breakpoint To find the browser width at which the content area reaches a breakpoint: ``` [Browser window width] = [Breakpoint] + [Main sidebar width] + [Secondary sidebar width] ``` | Sidebar | Width | | ------------------ | -------------------- | | Main XS | 12.5% of the window | | Main S | 18.75% of the window | | Main M | 25% of the window | | Main L half screen | 50% of the window | | Secondary sidebar | 96px | A main sidebar is never narrower than 280px with **White space: Spacious**, or 200px with **White space: Compact**. Main L half screen has no secondary sidebar option. **Example:** Main M with the secondary sidebar, White space Compact, breakpoint 1024px. ``` 1024 + 25% × X + 96 = X X = (1024 + 96) / 0.75 ≈ 1493px ``` 25% of 1493px is about 373px, above the 200px minimum, so the result holds: the layout switches at a window width of about 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://staylime.com/docs/avante-themes/developer/developer-docs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.