Quick Add Form
Quick Add Form lets shoppers select a WooCommerce variation and add it to the cart directly from a product card. Instead of navigating to the single-product page, the shopper opens an inline panel over the card, chooses the required options, adjusts quantity if available, and submits the variation form.
Quick Add is a feature inside Add To Cart, not a standalone element to search for in the Bricks element panel. The recommended setup uses (BU) Add To Cart in a product query loop. BricksUltimate also adds a Quick Add group to Bricks' standard product Add To Cart element.
On this page
- What Quick Add Does
- Prepare a Variable Product
- Enable the Required Features
- Build the Product Loop
- Configure Quick Add
- Style the Form Container
- Style the Close Control
- Style the Inner Add To Cart Button
- Variation Fields, Swatches and Quantity
- Use with Swatches for Loop
- Bricks Standard Add To Cart Element
- AJAX Lifecycle and Cart Updates
- Guests, Stock and Third-Party Plugins
- Mobile and Dynamic Layouts
- Practical Setup Examples
- Troubleshooting
- Frequently Asked Questions
- Storefront Test Checklist
- Technical Reference
- Related Documentation
What Quick Add Does
Quick Add is designed for product listings: shop/archive templates, a homepage product grid, a related-products loop, or another product query loop. It works with one product card at a time; it is not a multi-product order form or an entire product-page popup.
| Stage | What happens |
|---|---|
| The card renders | A variable product receives a Quick Add trigger and an initially empty form panel, unless its parent ID is excluded. |
| Shopper opens Quick Add | The variation form loads by AJAX on the first open. A loading state appears on the card while the request is running. |
| The form loads | WooCommerce's variation form initializes, then the BricksUltimate swatches and available quantity handlers initialize for the loaded markup. |
| Shopper chooses options | WooCommerce resolves the variation from the required attributes. A matching purchasable variation is needed before it can be added. |
| Shopper submits | The loaded form uses the AJAX single-product add-to-cart handler. Check the resulting WooCommerce cart and notices for the actual outcome. |
| The panel closes | The Close control dismisses the card panel. The frontend also closes Quick Add panels in response to the standard added_to_cart event. |
Closing and reopening a form that has already loaded can reuse that card's loaded form during the same page view. The add-to-cart event clears the loaded-state flag, so a later open can fetch the form again. This is an in-page behavior, not persistent storage across page reloads.
Prepare a Variable Product
- Edit a product in WooCommerce and choose Variable product in Product data.
- Configure its attributes, mark the attributes that define variations, and create the required variations.
- Give purchasable variations valid prices. Check enabled status, stock, stock-management settings, backorders, and any variation images.
- Publish the product and make it visible in the intended catalog/query.
- First verify that the same variation can be selected and added on the single-product page. If it fails there, correct the product or plugin configuration before testing Quick Add.
Use a complete variation combination when testing. Quick Add does not bypass a missing required attribute, an unavailable combination, or an extension's required options. A product can have valid parent-level information while one of its variations is unavailable.
Enable the Required Features
- Open Bricks > BricksUltimate > MISC.
- Enable the BricksUltimate Swatches feature and save. Quick Add uses this frontend script integration even if the immediate goal is opening a form rather than styling color swatches.
- Open Bricks > BricksUltimate > Woo Elements, enable Add To Cart, and save if using the BU element.
- Reopen the Bricks editor if the enabled controls or element are not yet visible.
Enabling native Bricks swatches is not a reason to skip the BricksUltimate Swatches setting required by this workflow. Do not assume a third-party swatch plugin registers the same scripts or events. Test the actual swatch integration used by the store.
Build the Product Loop
Recommended card structure
Products grid
Product card - query loop enabled, product query, position: relative
Product Image
Product title
Product price
(BU) Add To Cart - Using inside the query loop builder? enabled
- Create the product-card Div or Block and enable Bricks' query loop on that repeated card.
- Query WooCommerce products, not posts or variation attachments. Use a variable product in the preview/query while configuring Quick Add.
- Select the repeated product-card wrapper and set its CSS position to Relative in Bricks. This is the card that must contain the trigger and panel, not merely the outer grid containing every product.
- Add product content inside the repeated wrapper, such as a Product Image, title, price, and (BU) Add To Cart.
- On the BU Add To Cart element, enable Using inside the query loop builder?.
- Open Quick Add - Variable Products and enable Enable quick add action.
- Save and test the frontend with a real variable product. The interactive form is loaded on the storefront; do not rely on a fully working AJAX preview inside the builder.
Avoid wrapping the entire card in a product link when it also contains form controls. Link the image and title separately so links, dropdowns, swatches, quantity inputs, and buttons are not nested in a competing card-wide anchor.
Configure Quick Add
Open Quick Add - Variable Products on the BU Add To Cart element. The group is shown for the query-loop layout. Most controls below appear only after Enable quick add action is enabled.
| Control | Purpose |
|---|---|
| Enable quick add action | Enables the variable-product card panel and opening action. It does not turn simple products into variable-product forms. |
| Disable quantity field | Hides the quantity field inside the loaded Quick Add form. This is a visibility control, not a replacement for WooCommerce quantity validation or pack rules. |
| Exclude products | Comma-separated parent product IDs, such as 123,456, that should not receive Quick Add. Use a clean list without spaces. Other products in the loop can still use it. |
| Button text | A replacement-text setting for the Swatches for Loop integration. It is not the text of the inner form's submit button. |
Excluded variable products retain the ordinary Add To Cart behavior provided by their element and WooCommerce configuration, usually a product/options link. Exclusion does not hide the product from the query or remove it from the store.
Simple products do not get this variable-product panel. Their normal Add To Cart behavior remains in place. Grouped, external, bundled, subscription, composite, and other special product types are not automatically promised the same Quick Add workflow.
Style the Form Container
The panel appears over the product card and animates into view. The default implementation fills the card's available area. The inner form has its own vertical scrolling area when its contents exceed the panel space.
| Container control | What it changes |
|---|---|
| Padding | Space between the panel edge and loaded form contents. Leave enough space for the Close control. |
| Background color | The panel background over the product card. Use enough contrast to separate form controls from underlying product content. |
| Scrollbar width | Width of the inner form's WebKit scrollbar. |
| Scrollbar thumb color | Color of the draggable scrollbar thumb. |
| Scrollbar track color | Color of the scrollbar track. |
Scrollbar controls target WebKit scrollbar pseudo-elements, so appearance can differ by browser and operating system. Native scrolling remains the important behavior. Test touch scrolling, several attribute rows, a long option list, and validation notices in a narrow card.
The panel uses the card as its positioning context; it does not lock the background document like a full-screen modal. Default CSS hides overflowing card contents while the panel is open. Check clipping and stacking with badges, dropdowns, nested sliders, and neighboring cards rather than giving the whole page overflow rules.
Style the Close Control
The Close control sits inside the panel. The default text is Close, and the default icon is the Themify close icon.
| Close button control | Purpose |
|---|---|
| Text | Changes the visible Close wording. |
| Icon | Chooses the close icon. |
| Icon color | Sets the icon's color/fill. |
| Icon size | Adjusts the icon's size. |
| Gap | Exposes the close-icon spacing setting; verify its visible result with the chosen icon markup. |
| Position: Top / Right / Left | Moves the positioned close control relative to the panel. |
| Width | Sets the close control's width. |
| Padding | Adds space around the control. |
| Typography | Sets text appearance. |
| Background color | Sets its background. |
| Border | Sets the border and related appearance. |
Keep the close action visible above the form and easy to reach on mobile. Do not assume outside-click dismissal, Escape-to-close, a modal focus trap, or automatic focus return are supplied by this card-panel feature. Verify keyboard access on the finished page; a full modal experience needs the corresponding popup/off-canvas accessibility implementation.
Style the Inner Add To Cart Button
The Add To Cart Button subsection inside Quick Add styles the button in the loaded variation form. The element's normal Add To Cart settings style the outer product-card trigger. They are different controls and can have different labels and styles.
| Inner button control | What it changes |
|---|---|
| Text | Submit wording for the loaded form; default Add to cart. |
| Width / Height | Button dimensions. Size it for the actual card rather than applying a full-viewport height. |
| Padding | Button spacing. |
| Background | Background color. |
| Typography | Text styling. |
| Border | Border styling. |
| Box shadow | Shadow styling. |
| Icon | Adds an icon to the submit content. |
| Icon typography | Icon typography/size properties supported by the selected icon type. |
| Hover color | Icon hover color/fill. |
| Show only icon | Removes the submit text when an icon is configured. |
| Position | Left or Right placement for the icon beside text. |
| Gap between icon & text | Margin-based spacing for the icon. |
Prefer a visible submit label for clarity. If using icon-only output, verify the resulting accessible name and keyboard behavior; do not assume an icon alone describes the action to a screen-reader user. Check font-icon and SVG appearances separately because their sizing and spacing can differ.
Variation Fields, Swatches and Quantity
The form is generated from WooCommerce's product add-to-cart template. It is not an independently designed arbitrary Bricks form. Existing WooCommerce template overrides and compatible hooks can affect the generated markup.
Choose every required variation attribute, then check the selected variation's price and purchasability. Default Quick Add CSS shows variation price information but hides the variation description and availability blocks. Do not depend on those hidden blocks as the only way of communicating an important product restriction; WooCommerce's actual stock and add-to-cart validation still applies.
Use the Add To Cart element's variation, swatch, clear/reset, quantity, and related settings where applicable, and test the loaded form on the frontend. An external selector that updates an image or price must target the intended product/card, not every product in the grid. Give informative attributes clear labels and keep unavailable options distinguishable.
Three text settings that serve different purposes
- Outer Add To Cart text: the normal product-card trigger text from the element/product settings.
- Quick Add > Button text: the replacement-text integration used with Swatches for Loop when the variation selection changes.
- Quick Add > Add To Cart Button > Text: the actual submit label inside the AJAX-loaded form.
Hiding the quantity field does not grant permission to ignore WooCommerce minimums, maximums, increments, sold-individually rules, stock, or third-party validation. Always verify the actual quantity added to the cart. A form with required custom inputs may need more space or a full product-page workflow.
Use with Swatches for Loop
Swatches for Loop can expose variation choices directly in the product card. Quick Add instead opens a panel containing the form. They are related options, not identical interfaces.
- First verify Quick Add on a variable-product card without other variation UI.
- Add/configure Swatches for Loop in the same product-card context if shoppers should also select options directly from the listing.
- Set the appropriate button-sync settings in Swatches for Loop. Use Quick Add's Button text only for that replacement-text behavior.
- Test what happens before and after a complete variation selection: the button may participate in the swatch-driven add-to-cart action instead of simply opening the panel.
- Test clearing the selected variation so the original button behavior/text returns as intended.
Avoid displaying two independent variation forms for the same product unless the layout deliberately requires it and both are tested. Quick Add does not automatically synchronize every third-party swatch system. See Swatches for Loop and Swatches for their own setup.
Bricks Standard Add To Cart Element
BricksUltimate also extends Bricks' standard product Add To Cart element with a Quick Add group. The feature shares the Quick Add controls and frontend integration. This path is distinct from the BU element's Quick Add - Variable Products group.
If using the standard element, place it in the proper repeated product-card context, enable its Quick Add setting, keep BricksUltimate Swatches enabled, and verify that the frontend outputs the variable-product trigger and panel. Save the relevant page/template before testing so the AJAX form can resolve its settings.
This guide's main step-by-step workflow uses (BU) Add To Cart. Do not assume every newer modular WooCommerce element, third-party Add To Cart element, or custom HTML button receives the same extension. If the standard-element path differs with your Bricks version or template arrangement, reproduce the setup using the BU element before troubleshooting the integration.
AJAX Lifecycle and Cart Updates
The first opening request uses WordPress AJAX with action bu_load_variation_form. It supplies the product ID and the saved Bricks element/page identifiers so the rendered form can use its inner button text and icon settings. The endpoint returns form HTML; it is not the Bulk Add to Cart JSON API.
The frontend initializes WooCommerce's variation form and the available BricksUltimate swatch/tooltip handlers after insertion. Submission uses the loaded form and the single-product AJAX add-to-cart handler. The cart refresh flow includes standard WooCommerce fragment/event handling, and the Quick Add UI reacts to added_to_cart by closing its open state.
Do not treat a panel closing or an animation completing as proof that an order was placed, that payment succeeded, or that required options were accepted. Inspect WooCommerce notices and the actual cart. Custom mini-cart, cart-block, checkout, currency, and pricing integrations must be tested in the store's real configuration; universal fragment/block compatibility is not implied by the existence of the event.
The form-loader does not provide the Bulk Add to Cart element's per-row report, selected-page memory, estimate, or request-replay workflow. Keep the two features' troubleshooting steps separate.
Guests, Stock and Third-Party Plugins
The form-loading AJAX action is registered for guests and signed-in visitors. Store access controls, purchasing restrictions, WooCommerce settings, and active plugins can still prevent viewing or purchasing a product. Quick Add is not a private-store or customer-role access-control feature.
Current variation data determines which combination can be submitted. Loading a form does not reserve stock. Backorders and sold-individually restrictions are controlled by WooCommerce; product availability may change between opening the panel and adding to cart.
Product add-ons or other extensions may attach fields to the WooCommerce template, but that does not guarantee they initialize correctly after an AJAX insertion. File uploads, configurators, measurements, bundles, subscription choices, and required inputs can need plugin-specific JavaScript and submission handling. Test their complete workflow rather than hiding or bypassing validation.
For products that need a full configuration screen, put their parent IDs in Exclude products and let customers open the product page. That is usually clearer than trying to fit a complex configurator into a small card.
Mobile and Dynamic Layouts
On mobile, use a readable card width, sufficient control spacing, and a visible Close control. Test vertical scrolling inside the form when several attributes are present. Make sure long labels, translated text, quantity controls, and validation feedback fit without covering each other.
The swatch integration includes recall hooks for supported Bricks AJAX/query-result updates and popup-loaded events. This is not a guarantee for every third-party grid, slider, lazy loader, or popup. Test opening Quick Add on newly inserted cards after filtering/pagination, not just on the initially rendered grid.
For a nested slider, verify the panel is positioned inside the intended product card and is not clipped by an outer slide wrapper. Avoid solving a single-card clipping issue by globally removing overflow rules from the entire slider or page.
The builder is useful for configuring controls and card styling, but the loaded form and its AJAX interaction must be tested on the storefront. Do not expect Quick Add to share the Bulk Add to Cart element's five-row demo preview.
Practical Setup Examples
Clothing shop
Use a variable-product card for a shirt with Color and Size. Put product image/title/price and BU Add To Cart in the repeated card, set the card to Relative, enable loop mode and Quick Add, then style the panel and inner button. Choose both attributes on the frontend and confirm the correct variation ID, quantity, and price in the cart.
Homepage product selection
Build a product query loop on the homepage rather than manually duplicating one product's form. Quick Add resolves each card's current product context. Keep the image and title as separate links, and verify that each card opens its own form rather than the same product repeatedly.
Mixed catalog
Use the same product loop for simple and variable products. Simple products keep their normal action; eligible variable products receive Quick Add. Exclude complex variable products that need uploads or detailed configuration, leaving their normal product/options links available.
Compact repeat-purchase interface
Use Quick Add when the shopper configures and adds one variable product at a time from cards. If the customer needs SKU search, many quantities across result pages, advanced filters, custom columns, and one combined submit action, use Bulk Add to Cart instead.
Troubleshooting
| Symptom | Check |
|---|---|
| Cannot find a Quick Add Form element | It is a feature of Add To Cart, not a separately registered element. Select BU Add To Cart in a product loop and open Quick Add - Variable Products. |
| Quick Add group is missing on BU Add To Cart | Enable Using inside the query loop builder? and use the element inside the repeated product card. Reopen Bricks after enabling the element/features. |
| Clicking opens the product page instead | Check global BU Swatches activation, Enable quick add action, variable product type, Exclude products, loaded scripts, and whether another button/anchor handler intercepts the click. |
| Panel covers the grid instead of the card | Set the repeated card wrapper to Relative. Verify the trigger and wrapper are inside the nearest intended product query-loop item. |
| Empty panel or loading never resolves | Inspect the bu_load_variation_form request and JavaScript console. Check product visibility, saved element/page IDs, failed AJAX responses, template output and scripts. A visible open panel is not proof that the form loaded successfully. |
| Wrong product or wrong submit label | Verify product query context and the saved element/page settings used by the AJAX form. Save changes and clear relevant page/style caches. Avoid reusing manually copied product IDs. |
| Swatches are visible but do not respond | Check BU Swatches activation, WooCommerce variation-form script loading/initialization, duplicate variation forms, and third-party swatch conflicts. Test the same product on its single page. |
| Add To Cart remains unavailable | Select every required attribute and a valid purchasable combination. Check prices, stock, enabled variations, required add-ons and WooCommerce validation. |
| Changing Button text does not change the form submit label | Quick Add's first Button text field is for Swatches for Loop synchronization. Use Quick Add > Add To Cart Button > Text for the inner submit label. |
| Quantity is hidden or unexpected | Check Disable quantity field, WooCommerce stock/sold-individually/min/max rules and any quantity extension. Hiding the input does not change validation. |
| Variation description or stock notice is absent | Default Quick Add CSS hides variation description and availability blocks. Check the actual variation and cart validation rather than relying on those blocks. |
| Close control is clipped or difficult to reach | Adjust its Top/Right/Left position, width and padding. Leave room in the panel and inspect outer wrapper overflow/stacking on mobile. |
| Scrollbar styling does not match another browser | The supplied controls target WebKit scrollbar pseudo-elements. Verify scrolling itself and the browser's native scrollbar behavior. |
| Mini-cart does not update as expected | Check WooCommerce fragment scripts, cart events and the actual custom mini-cart/blocks integration. Test the cart contents, not only the card animation. |
| It works initially but not after AJAX filtering | Verify the grid uses supported update events and that inserted cards contain the expected markup/scripts. Check the actual loader integration rather than globally rebinding click handlers repeatedly. |
| Add-on fields fail only inside Quick Add | The extension may require initialization or submission handling not supplied by this AJAX-loaded form. Exclude the affected product and use its product page until a specific integration is available. |
| Styles do not update | Save the source page/template, regenerate Bricks CSS, clear relevant caches, and check instance/global-class overrides. Test after loading the form, not only the empty wrapper. |
Frequently Asked Questions
Is Quick Add the same as Quick View?
No. Quick Add is a variation form panel inside a product card. A Quick View popup may show images, descriptions and other product content in a larger modal. Use the relevant popup/builder feature for that experience.
Is it the same as Bulk Add to Cart?
No. Quick Add configures one variable product per card interaction. Bulk Add to Cart is a searchable multi-product ordering interface with quantities across pages and a combined submit action.
Can I use it on the homepage?
Yes, with an actual WooCommerce product query loop and the same relative card wrapper/setup. It is not restricted to the shop archive.
Do all products need to be variable?
No. A mixed loop can include simple products. Only eligible non-excluded variable products receive the Quick Add panel; other products keep their normal action.
Does the form reload on every open?
Not necessarily. The current frontend can reuse the loaded form after closing/reopening the same card. The add-to-cart event clears its loaded-state flag. Page reloads, replaced cards and other dynamic changes can require another request.
Is the Close control a full modal accessibility implementation?
No. It dismisses an inline card panel. Verify keyboard access yourself; outside-click close, Escape dismissal, focus trapping and body-scroll locking should not be assumed.
Can required product add-ons be ignored?
No. Required options and WooCommerce restrictions must be respected. Use Exclude products and a full product-page workflow when an extension is not compatible with the loaded form.
Storefront Test Checklist
- Verify a real variable product works on its single-product page.
- Open Quick Add in at least two different cards and confirm each uses the correct product.
- Choose complete and invalid/unavailable attribute combinations.
- Test quantity changes, hidden quantity, stock limits, backorders and sold-individually rules where applicable.
- Check the outer trigger label separately from the inner submit text and icon.
- Submit once and verify the correct variation and quantity in the actual cart and mini-cart.
- Close/reopen a card and test again after an add-to-cart event.
- Verify Exclude products leaves a usable product/options link.
- Test narrow mobile cards, scrolling, long labels and keyboard access to Close/Submit.
- Repeat after AJAX pagination/filtering and with the store's real add-on, pricing, swatch and cart extensions.
Technical Reference
The shared controls are defined in includes/Trait/WooQuickAddFormControls.php. The BU element implementation is includes/Elements/WooAddToCart.php; Bricks' standard-element extension is includes/ElementControls/ProductAddToCart.php. Form HTML loads through includes/Ajax.php, and the card/swatches frontend behavior is in assets/js/elements/swatches.js with the shipped minified asset. Shared Quick Add styling is in assets/css/elements/bu-woo.css and its minified asset.
Useful selectors for inspection or carefully scoped overrides:
| Selector/state | Meaning |
|---|---|
.brxe-loop-builder-on |
Product-loop wrapper used as the card context |
.quick-add-btn |
Add To Cart wrapper carrying the Quick Add trigger behavior |
.quick-add-wrapper |
Panel wrapper, with saved data-element-id and data-page-id |
.qa-cart-form |
Scrollable target receiving the loaded WooCommerce form |
.qa-close-btn |
Close-control wrapper |
.bu-loading-qa-form |
Loading state on the product card |
.quick-add-open |
Open state on the product card |
.qa-from-loaded |
Loaded-form state used for reopening behavior |
.wrapper-overflow-hidden |
Card overflow/positioning state during the open panel |
Prefer builder controls before custom CSS. Scope any override to the intended card or element so it does not affect every product in the catalog. Quick Add does not expose the Bulk Add to Cart bu_batc_* event API or its configuration endpoints.