> ## 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.
# Settings Reference
> Complete reference for all BoxBuilder settings across all 6 tabs.
BoxBuilder settings are found at **BoxBuilder → Settings** in your WordPress admin. Settings are organized into 6 tabs: General, Display, Labels, Gift Message, Cart, and Appearance.
Click **Save Settings** at the bottom of any tab to apply changes. Settings apply globally to all box products unless overridden at the individual product level.
***
## General
The General tab controls layout, positioning, interaction behavior, the box summary panel, progress indicators, and mobile settings.
### Product Layout
| Setting | Description | Options | Default |
| ----------------- | ------------------------------------------ | ---------- | ------- |
| Layout Style | How products are displayed in the builder | Grid, List | Grid |
| Products Per Page | Number of products shown before pagination | Any number | 12 |
Grid layout works best for visual browsing (e.g., chocolates, flowers). List layout is better when product details matter (e.g., items with descriptions or variations). Recommended: 8–16 products per page for optimal performance.
### Builder Position
| Setting | Description | Options | Default |
| ------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Position on Product Page | Where the builder appears on the product page | After Product Details Block, Before Product Tabs, Replace Product Tabs, After Product Tabs, After Price, After Short Description, After Add to Cart Form, After Product Meta, Shortcode Only | Before Product Tabs |
| Summary Panel Position | Which side the box summary panel appears on | Right Side, Left Side | Right Side |
**Choosing the right position:**
* **FSE/Block themes** (e.g., Twenty Twenty-Four): Use "After Product Details Block"
* **Classic themes** (e.g., Storefront, Astra): "Before Product Tabs" is recommended
* **Page builders** (Elementor, Divi, etc.): Use "Shortcode Only" and place `[boxbuilder]` where you want
### Interaction
| Setting | Description | Options | Default |
| ----------------- | ------------------------------------------------- | ------------------------------------------ | -------------- |
| Add to Box Mode | How customers add products to the box | Button Click, Card Click (quick add), Both | Button Click |
| Quantity Controls | When +/- quantity buttons appear on product cards | Always Visible, On Hover, After First Add | Always Visible |
"Card Click" mode is faster for high-volume stores where customers add many items quickly. "Both" gives customers the flexibility to use either method.
### Box Summary
The summary panel shows selected items and the running total.
| Setting | Description | Options | Default |
| --------------------------- | --------------------------------------- | ----------------------------- | --------- |
| Display Mode | How items appear in the summary panel | List View, Slot Grid, Minimal | List View |
| Show thumbnails in summary | Display product images next to items | Checkbox | Enabled |
| Show item prices in summary | Display individual prices for each item | Checkbox | Enabled |
**Slot Grid** mode shows a visual representation of the box filling up — great for gift boxes where the "filling" experience matters. **Minimal** keeps the summary compact with just item names and counts.
### Progress Indicators
| Setting | Description | Options | Default |
| ---------------------------------------- | ------------------------------------------------- | --------------------------------------------------------- | ------------------------- |
| Show progress indicator | Display visual feedback for box completion | Checkbox | Enabled |
| Progress Style | Visual style for the progress indicator | Progress Bar, Percentage (50%), Slot Dots, Counter (6/12) | Progress Bar |
| Show "almost full" encouragement message | Display a motivational message when close to full | Checkbox | Enabled |
| Message Text | The encouragement message text | Text input | "Add {count} more items!" |
Use `{count}` in the message text as a placeholder for the number of remaining items. For example, "Add {count} more items!" becomes "Add 3 more items!" when there are 3 slots left.
### Mobile
| Setting | Description | Options | Default |
| ----------------------------------- | -------------------------------------------------------------------- | ---------------------------------------- | -------------- |
| Mobile Layout | How the builder displays on mobile devices | Stacked (default), Tabbed (switch views) | Stacked |
| Summary Position | Where the summary appears relative to products (stacked layout only) | Below Products, Above Products | Below Products |
| Sticky Add to Cart button on mobile | Fix the Add to Cart button at the bottom of the screen | Checkbox | Enabled |
**Stacked** layout shows products and summary vertically. **Tabbed** layout lets customers switch between "Products" and "Your Box" views — useful when screen space is limited.
***
## Display
The Display tab controls product card information, stock management, and search/filter options.
### Product Cards
| Setting | Description | Default |
| ------------------------------- | ------------------------------------- | ------- |
| Show price on each product card | Display the product price on the card | Enabled |
| Display "Only X left!" badge | Show a low stock warning badge | Enabled |
Disable "Show price" for fixed-price boxes where individual item prices are irrelevant — customers only need to know the total box price.
### Stock Management
| Setting | Description | Options | Default |
| --------------------- | -------------------------------------------------- | -------------------------------------------------------------------- | -------------------------- |
| Out of Stock Products | How to handle products with zero stock | Show all (no indicator), Show with badge (disabled), Hide completely | Show with badge (disabled) |
| Low Stock Threshold | Stock level that triggers the "Only X left!" badge | Any number | 5 |
"Show with badge (disabled)" keeps the product visible but prevents customers from adding it — this avoids confusion about missing products. "Hide completely" removes them entirely from the grid.
### Search & Filter
| Setting | Description | Options | Default |
| ---------------------- | ------------------------------------------ | -------------------------------- | -------------------- |
| Enable product search | Show a search bar above the product grid | Checkbox | Enabled |
| Search Placeholder | Placeholder text shown in the search field | Text input | "Search products..." |
| Enable category filter | Show category filter controls | Checkbox | Enabled |
| Category Filter Style | How category filters are presented | Horizontal Tabs, Dropdown Select | Horizontal Tabs |
Horizontal tabs work best when you have 2–5 categories. For 6+ categories, switch to the dropdown to avoid wrapping and clutter.
***
## Labels
The Labels tab lets you customize all user-facing text strings in the builder interface.
### Products Section
| Setting | Description | Default |
| ----------------- | ----------------------------------------------------- | ----------------------------------------- |
| Section Title | Heading above the product grid | "Choose Your Products" |
| Section Subtitle | Subtitle text below the heading (leave empty to hide) | "Select items to add to your custom box." |
| Add to Box Button | Text on the add button for each product | "Add to Box" |
### Box Summary Panel
| Setting | Description | Default |
| -------------------------------------- | ----------------------------------------- | -------------------------------------------- |
| Panel Title | Heading of the summary sidebar | "Your Box" |
| Slots Remaining Text | Text showing remaining capacity | "{count} slots remaining" |
| Empty Box Title | Title shown when no items have been added | "Your box is empty" |
| Empty Box Hint | Helper text when box is empty | "Click on products to add them to your box." |
| Add to Cart Button | Text on the final add-to-cart button | "Add Box to Cart" |
| Box Size Selector Title Pro | Heading above box size options | "Choose Your Box Size" |
Use `{count}` in the "Slots Remaining Text" field as a placeholder for the number. For example, "{count} slots remaining" becomes "4 slots remaining" when there are 4 empty slots.
***
## Gift Message
The Gift Message tab controls whether customers can add a personal note to their box.
### Gift Message Toggle
| Setting | Description | Default |
| ------------------------------------ | ----------------------------------------------------- | -------- |
| Enable gift message field | Show the gift message textarea in the builder | Enabled |
| Require customers to enter a message | Make the gift message mandatory before adding to cart | Disabled |
### Field Settings
| Setting | Description | Default |
| ---------------- | ------------------------------------------------------- | --------------------------- |
| Field Label | Label shown above the text area | "Gift Message" |
| Placeholder Text | Placeholder inside the empty text area | "Add a personal message..." |
| Max Characters | Maximum character limit for the message (0 = unlimited) | 500 |
Keep the character limit reasonable — 500 characters is typically enough for a thoughtful gift message without allowing excessively long text that could cause display issues on packing slips.
***
## Cart
The Cart tab controls how boxes behave in the WooCommerce cart and after adding to cart.
### Cart Display
| Setting | Description | Default |
| ---------------------------------------------- | ------------------------------------------------------------ | -------- |
| Show list of items inside the box on cart page | Display individual box contents beneath the box item in cart | Enabled |
| Allow changing box quantity in cart | Let customers increase/decrease box quantity from the cart | Disabled |
### After Add to Cart
| Setting | Description | Options | Default |
| ----------- | -------------------------------------------------- | -------------------------------------- | --------- |
| Redirect To | Where to send customers after adding a box to cart | Cart Page, Checkout Page, Stay on Page | Cart Page |
### Box Sizes Pro
These settings control how multiple box sizes are presented when using [Box Sizes](/plugins/boxbuilder/box-sizes) in BoxBuilder Pro.
| Setting | Description | Options | Default |
| -------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------- |
| Size Display Style | How size options are shown to customers | Cards (dropdown on mobile), Dropdown selector | Cards (dropdown on mobile) |
| Cards Per Row | Number of size cards per row (cards style only) | 2, 3, 4, 5 | 3 |
| Size Change Behavior | What happens when a customer switches to a smaller size and items exceed the new capacity | Keep items that fit, remove excess; Prevent size change; Show warning and ask to confirm | Keep items that fit, remove excess |
***
## Appearance
The Appearance tab controls colors, card styling, and advanced options.
### Brand Colors
| Setting | Description | Default |
| ------------- | -------------------------------------------------------------- | --------- |
| Primary Color | Main accent color used for buttons, selected states, and links | `#5c6ac4` |
| Success Color | Color used for "added" badges and confirmation states | `#28a745` |
Choose a primary color that matches your store's branding. The color picker supports hex values — click "Default" to reset to the original color.
### Card Styling
| Setting | Description | Options | Default |
| ------------ | ------------------------------ | --------------------------------------------------------------------------------------------- | -------------- |
| Corner Style | Border radius of product cards | Square (0px), Slightly Rounded (4px), Rounded (8px), More Rounded (12px), Very Rounded (16px) | Rounded (8px) |
| Card Shadow | Shadow effect on product cards | None (Flat), Light (Subtle), Medium (Prominent) | Light (Subtle) |
### Advanced Pro
| Setting | Description | Default |
| ---------------------------------- | ------------------------------------------- | ------- |
| Enable logging for troubleshooting | Write debug information to WooCommerce logs | Enabled |
Leave logging enabled during setup and testing. You can disable it on production sites to avoid unnecessary log file growth. Logs are accessible at **WooCommerce → Status → Logs**.