> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftlywp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Template Overrides

> Customize the BoxBuilder frontend template for full control over the HTML output.

BoxBuilder uses a single frontend template file to render the box builder UI on product pages. You can customize the builder's output using hooks, CSS, or by modifying the template directly in child themes.

## Frontend Template

The builder UI is rendered from a single template file:

```
boxbuilder-pro/templates/boxbuilder-frontend.php
```

This template handles the complete builder interface including:

* Product grid / list layout
* Box summary panel
* Progress indicators
* Gift message field
* Add to Cart button
* Size selector (Pro)

## Template Variables

The following variables are available inside the template:

| Variable    | Type   | Description                                                                 |
| ----------- | ------ | --------------------------------------------------------------------------- |
| `$box_id`   | int    | The WooCommerce product ID for the box                                      |
| `$config`   | array  | The box configuration array (capacity, pricing model, product source, etc.) |
| `$css_vars` | string | CSS custom properties for theming (primary color, success color, etc.)      |

The template also reads global plugin options:

| Option Key                           | Description                            |
| ------------------------------------ | -------------------------------------- |
| `boxbuilder_mobile_layout`           | Mobile layout mode (stacked or tabbed) |
| `boxbuilder_mobile_summary_position` | Summary position on mobile             |
| `boxbuilder_mobile_sticky_cart`      | Whether sticky cart button is enabled  |
| `boxbuilder_summary_display_mode`    | Summary panel display mode             |
| `boxbuilder_summary_show_thumbnails` | Show thumbnails in summary             |
| `boxbuilder_summary_show_prices`     | Show prices in summary                 |
| `boxbuilder_progress_style`          | Progress indicator style               |
| `boxbuilder_add_mode`                | Add to box interaction mode            |
| `boxbuilder_qty_controls_display`    | Quantity controls display behavior     |

## Customizing with Hooks

The recommended way to add content before or after the builder is with hooks:

```php theme={null}
// Add content before the product grid
add_action( 'boxbuilder/before_product_grid', function( $box_id, $config ) {
    echo '<div class="my-custom-banner">Build your perfect gift!</div>';
}, 10, 2 );

// Add content after the add to cart button
add_action( 'boxbuilder/after_add_to_cart_button', function( $box_id ) {
    echo '<p class="my-custom-note">Free shipping on all boxes!</p>';
}, 10, 1 );
```

## Customizing with CSS

For visual changes, use the [Appearance settings](/plugins/boxbuilder/appearance) or add custom CSS. All BoxBuilder elements are namespaced under `.boxbuilder-wrap` with `.boxbuilder-` prefixed class names.

```css theme={null}
/* Example: customize product cards */
.boxbuilder-wrap .boxbuilder-product-card {
    background-color: #f9f9f9;
    border: 1px solid #e0e0e0;
}
```

## Customizing with JavaScript

BoxBuilder's frontend is a Vue.js application. You can interact with it via the localized `boxbuilderData` object:

```js theme={null}
// Available data from wp_localize_script
console.log( boxbuilderData.ajaxUrl );  // AJAX endpoint
console.log( boxbuilderData.nonce );    // Security nonce
console.log( boxbuilderData.i18n );     // Translatable strings
```

<Warning>
  Modifying the Vue.js application directly is not recommended as it may break with plugin updates. Use hooks and CSS for customizations whenever possible.
</Warning>