Bulk Add to Cart
(BU) Bulk Add to Cart creates a searchable WooCommerce product table or compact list where customers enter quantities for several products and add them to the cart in one request. It is useful for wholesale catalogs, trade customers, repeat purchases, parts lists, and quick-order pages. Customers can search by product name or SKU, choose individual variation rows, filter the catalog, and review selections made across several result pages.
This is a Bricks element, not a product-management screen, a CSV importer, or an alternative checkout. WooCommerce still validates products, stock, required options, and final pricing. The submit button is labeled Add Selected to Cart by default.
On this page
- Setup
- Ordering
- Advanced Filters
- Custom Columns
- Live Order Estimate
- Safety and Scope
- Interrupted Requests
- Caching and Compatibility
- Bricks Presentation Controls
- Live Dynamic Tags
- Events and Bricks Interactions
- Practical Setups
- Troubleshooting
- Frequently Asked Questions
- Technical Reference
- Storefront Test Checklist
- Related Documentation
Setup
- Activate WooCommerce and BricksUltimate.
- Open Bricks > BricksUltimate > Woo Elements, enable Bulk Add to Cart, and save.
- Reopen Bricks and add (BU) Bulk Add to Cart to a page or template.
- Under Products, optionally include/exclude parent products or enter product category IDs. Child categories are included. Set products per page and the guest/login and stock visibility options.
- Under Content, select optional columns and edit labels. Product and Quantity remain visible. Show result column is off by default; enable it to put row feedback in a dedicated column in table layouts.
- Under Presentation, choose desktop and mobile layouts independently. A good starting point is Table on desktop and Compact list on mobile.
- Enable only the Advanced Filters you need. Add any Custom Columns, and optionally enable Live order estimate.
- Save the page and test search, quantities, variations, selected-items review, and a cart submission as both a guest and a signed-in customer where applicable.
Product requirements and supported scope
Published, visible simple products and complete published variations are supported. A variable parent is a group heading; customers order its child variations, not the parent itself. A simple product needs a purchasable price and stock availability. Backorders follow WooCommerce's product settings. Hidden, private, and draft products cannot be exposed by changing request IDs. Grouped, external, bundle, subscription, or other special product types are not automatically supported.
Create SKUs and variation data in the normal WooCommerce product editor. An empty Include products selection means all eligible products, not an empty catalog. Use product restrictions when a page should offer only a particular range; frontend filters are optional browsing tools, not replacements for those restrictions.
Products controls
| Control | How to use it |
|---|---|
| Include products | Choose parent products to make an explicit catalog. Leave empty to include all eligible products. Including a variable parent allows its eligible variations. |
| Exclude products | Remove parent products and their variation groups from this form. Exclusions still apply when Include products is used. |
| Category IDs | Enter comma-separated product category IDs, such as 12,34. Their descendants are included. This is a fixed form restriction, different from the customer's category dropdown. |
| Products per page | Choose between 5 and 30 parent/simple-product results; default 10. Expanded variation groups have their own pagination using this page size. |
| Auto-load variations | Expand visible variable products automatically. Leave off for the lighter click-to-load workflow. |
| Show out-of-stock products | Include unavailable rows for information. It does not make out-of-stock products purchasable. |
| Logged-in customers only | Restrict catalog requests and ordering through this element to authenticated customers. Enforce any wider wholesale/private-store access with the site's access-control solution as well. |
Content controls
| Control | What it changes |
|---|---|
| Product images | Shows product thumbnails beside names. |
| Optional columns | Select and order SKU, Options, Price, and Availability. Product and Quantity remain visible. |
| Show result column | Adds a dedicated feedback column in table mode. Off by default; otherwise feedback sits below the product. Compact lists always use inline feedback. |
| Row spacing | Shared Comfortable or Compact default. Device-specific spacing in Presentation can override it. |
| Sticky action bar | Keeps the selection summary and order controls visible while scrolling within the layout. Test its behavior inside scrollable popups and off-canvas panels. |
| Disable motion | Turns off the element's transitions and loading animations. Device reduced-motion preferences are respected independently. |
| Text fields | Customize the heading, search label/placeholder, action labels, standard column headings, and other available messages in their corresponding groups. |
Custom columns appear after the optional standard columns and before Quantity. Enabling the estimate appends Est. subtotal; an enabled table Result column follows it. Changing visible columns does not disable validation or hide the overall submission report. 6. Customize the heading, table/header, rows, search/quantity fields, submit/secondary buttons, and success/error colors through the element controls. Standard Bricks wrapper styles also apply.
Under Content, choose Comfortable or Compact row spacing. Sticky action bar keeps the summary and submit button visible within the element while scrolling; leave it off where the surrounding layout already has sticky controls. Disable motion turns off the component's subtle transitions and loading effects. Device reduced-motion preferences are respected automatically.
Under Product Rows, use Accent color and Selected row background to customize selection feedback and the shared accent. Availability badges distinguish in-stock, backorder, unavailable, and configuration-required states with text as well as color. Existing typography, padding, background, border, hover, and feedback controls remain available.
The element can be placed in ordinary pages, templates, off-canvas content, and AJAX-loaded Bricks popups. Multiple forms keep independent selections. It does not emit a nested HTML form, and Enter in its inputs will not submit an enclosing checkout form. Test any third-party popup mechanism's asset loading separately.
The builder editor displays the latest five published products as read-only demo rows, using their real names, SKUs, prices, images, and availability. PHP renders these rows directly, without waiting for JavaScript or AJAX. This preview ignores the frontend catalog filters so the table can be styled immediately. It does not run product-search or cart requests. If fewer than five published products exist, it displays the available products.
With Auto-load variations enabled, the builder also renders up to five published variations beneath each variable demo product. These extra preview rows are read-only and do not use AJAX; the frontend uses the normal paginated variation search.
Ordering
The customer's workflow
- Search for a product name, parent SKU, or variation SKU, or use the enabled filters.
- Set a quantity with the plus/minus controls or type it directly. For a variable product, open its variations unless automatic loading is enabled.
- Continue searching or paging. The current form remembers selected IDs and quantities.
- Open Selected items to review every selected row, including rows not visible in the current results. Change a quantity or set it to zero to remove that selection.
- Select Add Selected to Cart. Read the summary and per-product report above the table. Open View cart to review actual cart prices and proceed to checkout.
Quantity rules and result handling
- Search by product name, parent SKU, or variation SKU. A variation-SKU match reveals its parent; expand Choose variations to see matching child rows.
- Product and variation results are paged on the server. By default, variations load only when expanded. Enable Products > Auto-load variations to expand them automatically after each results page or search loads. Automatic loading runs at most two child requests at a time and loads the first variation page for each visible variable product, not every variation in the catalog. Customers can still collapse a group or use its variation-page controls. Quantity selections survive searches and pagination. The default remains click-to-load for lighter catalog browsing.
- Enter a positive quantity to select an orderable row. Zero clears that row. Quantities remain selected across search and page changes within the same instance, but do not persist after a page reload.
- Use the minus/plus buttons for quick quantity changes, or type directly. Plus starts at the product's minimum, then follows its quantity increment; minus returns from the minimum to zero to deselect. The maximum and request-state limits disable the appropriate buttons. Arrow Up/Down use the same rules. Builder preview buttons remain disabled.
- Up to 50 distinct products/variations can be sent per batch. The summary counts selected rows and units, not a promised final price.
- Selected items opens a focused view of quantities chosen across all pages. Adjust a quantity or set it to zero there without searching for the product again. All products returns to the catalog.
- Add Selected to Cart submits all selections, including those on other pages. WooCommerce checks stock, existing cart quantities, purchasability, variation data, and add-to-cart validation hooks.
- Successful rows reset to zero. Failed rows retain their quantities and show the rejection reason. The submission summary and per-product results list appear above the table, including rows hidden by the current search. The selection count and order controls remain below the table.
- One fragment response and
added_to_cartevent refresh the mini-cart and WooCommerce listeners for the batch. The event passes a detached button so WooCommerce and Bricks single-product handlers cannot insert a second cart link or reset the bulk submit text. Its jQuery.data('buBatcForm')value points to the source form; prefer the native bulk-add-to-cart events below for form-specific actions. WooCommerce Blocks' standard event bridge can invalidate its cart store. Test custom cart/checkout extensions in the target store.
Advanced Filters
Enable the filters
- Open the element's Advanced Filters group and select the entries in Available filters.
- For Brands, select the public taxonomy registered by the store's brand plugin. Do not assume every brand plugin uses the same taxonomy name.
- For Attributes, choose the global WooCommerce attributes that customers should filter by. A maximum of six is used.
- Customize the filter labels if needed, save, and test combinations on real products. Check a variation group as well as a simple product.
Open Advanced Filters > Available filters in the builder. All filters are optional and off by default. Filters combine with search and the element's signed Include, Exclude and Category restrictions; they cannot expand the configured catalog scope.
- Categories: matches a category and its descendants. Variations inherit the parent category.
- Brands: select the registered public product taxonomy used by your brands plugin. WooCommerce's
product_brandis the default when available. Variations inherit the parent brand. - Attributes: choose up to six global WooCommerce attributes, such as
pa_colororpa_size. Each becomes a dropdown; multiple selections combine with AND. Local text-only attributes are not filter taxonomies. - Price range: minimum and/or maximum WooCommerce catalog lookup prices, including current sale prices. These use the lookup's stored currency/tax basis, not the live estimate's tax-exclusive basis. Cart discounts, fees and add-ons are not included. Currency/customer-role pricing extensions need a matching catalog-price integration.
- Availability: In stock or On backorder. Out of stock is offered only when Products > Show out-of-stock products is enabled. Filtering does not reserve stock.
- Previously purchased: uses only the logged-in customer's own paid orders. Expanded rows include only exact purchased variations. Guests see a disabled checkbox and sign-in message; email addresses are not used to discover history. Cancelled, fully refunded and unpaid order statuses do not qualify.
Variable-product conditions must match the same variation: a red variant at $18 and a blue variant at $30 do not make the parent match "red, minimum $20". Wildcard variations can match attributes but still require configuration on the product page.
Changes reset to page one and preserve selected quantities across all pages. Clear filters clears these filters only, not search text or quantities. Filters also apply to automatic variation expansion and child pagination. Selected-items review can still show products outside the current filter results. Filter editing is locked while a cart request is unresolved.
Dropdown options load separately through the signed bu_batc_filters endpoint with a retry state. Each taxonomy dropdown shows up to 200 non-empty terms ordered by name. Options are bounded, not an unlimited remote browser or a live faceted count; a term may have no matches under another active filter. Labels are editable in Advanced Filters. Search and Quantity styles apply to inputs; the filter group has its own typography, background, border and padding controls.
History uses WooCommerce's order CRUD API, including HPOS, and is cached per user for ten minutes. Order updates, status changes, deletion and trashing invalidate the customer's cache. The first uncached lookup reads paid orders in batches of 100, so very large histories can take longer. No other customer's orders or order details are returned to the browser.
Currency integrations can convert entered bounds to the catalog lookup's currency/basis:
add_filter( 'bu_batc_filter_catalog_price', function( $amount, $bound, $currency ) {
return $amount; // Convert using the store's pricing integration when needed.
}, 10, 3 );
Custom Columns
Create a column
- Open Custom Columns > Additional columns and add a repeater item.
- Enter a clear heading and choose its Source.
- Enter the attribute/field key, or enter Fixed text when that source does not need a product-specific key.
- Enable parent fallback when variations should inherit a shared value. Set Empty value text for products without that value.
- Drag items into the desired order. Save and compare the table and compact-list layouts on the storefront.
In Custom Columns > Additional columns, add and reorder up to twelve columns. They appear after optional standard columns and before Quantity, in tables and compact lists.
| Setting | Meaning |
|---|---|
| Heading | Column title and compact-list field label |
| Source | Product attribute, Pack size, Delivery information, or Approved custom field |
| Attribute or field key | Global attribute such as pa_size, local attribute name such as Material, or public product meta key such as pack_size |
| Fixed text | Used when the key is empty, such as "Pack of 6" or "Dispatches in 2 days" |
| Use parent value when empty | Read the parent value when a variation has no value |
| Empty value text | Fallback for missing or non-scalar values |
For example, Color can use pa_color, Pack size can read pack_size, and Delivery can use fixed text. Pack size is display information, not a quantity-multiple rule. Delivery text is not a live shipping quote or promised arrival calculation.
Explicitly configured public field keys form the signed frontend allowlist; visitors cannot request arbitrary meta. Protected keys, normally starting with _, are blocked. Approval is checked when configuring and when reading values. Arrays/objects are not expanded; numeric zero is preserved. Values are stripped of HTML and limited to 300 characters, then rendered as text.
Only approve a protected field after verifying it is safe to publish:
add_filter( 'bu_batc_allowed_custom_field', function( $allowed, $key ) {
return $allowed || $key === '_public_pack_size';
}, 10, 2 );
Do not approve tokens, credentials, purchase notes or private downloadable-file metadata. The field must still be explicitly selected in the builder. Custom Columns provides shared typography/background/border/padding controls, and standard row/header styles also apply. Builder previews render configured values directly without frontend AJAX.
Live Order Estimate
Enable and choose a calculation mode
- Open Live Estimate and turn on Live order estimate. It is optional and off by default.
- Keep Client-side (instant) for a lightweight estimate based on current unit-price snapshots. Use Server-side (advanced) when a pricing integration needs the complete selected quantities to calculate a price.
- Keep the exclusion note visible. Update its wording only if it remains accurate for the store's implementation.
- Select products on more than one result page and confirm the total includes all selections, not just the visible page.
Enable Live Estimate > Live order estimate in the Bricks element. It is off by default, so existing forms make no extra pricing requests. Enabling it adds an Est. subtotal field per row and an Estimated product total above the table. Edit the estimate labels, explanatory note and state messages in the same section; typography, background, border and padding controls style the estimate band. Existing row/table styles apply to the subtotal column and compact-list field.
Estimates include every selected row across all result pages, searches, expanded variations and the Selected items view. Cleared selections and successfully added rows no longer contribute; failed cart rows remain selected. Choose Calculation mode:
- Client-side (instant) is the default when estimates are enabled. The server supplies tax-exclusive numeric unit-price snapshots with the existing catalog/variation responses. Quantity changes calculate immediately in the browser and make no pricing requests. Decimal-string integer arithmetic avoids floating-point artifacts, rounds each row to the currency precision, then sums rounded rows. Prices are never parsed from display HTML.
- Server-side (advanced) sends debounced selection requests. Choose it for quantity-dependent price integrations or custom server-side price formatting. Rapid changes are combined and stale responses are ignored.
Both modes preserve quantity-input focus. Formatting uses WooCommerce's current symbol, currency position, decimal precision, decimal/thousand separators and trailing-zero setting. Client mode supports currency precision from zero to twenty decimal places. Custom wc_price markup or other arbitrary price-output filters require server mode; they cannot be reproduced universally by browser formatting.
The server reads current WooCommerce product prices in the current customer's session, including product getter filters for customer roles or currencies. Client mode multiplies these supplied unit prices; server mode calculates complete line amounts. Browser estimates can be edited by a visitor and are never trusted for actual cart pricing. This is a selected-product estimate, not the current cart total. It does not add products, recalculate the real cart, reserve stock, or validate arbitrary third-party required fields.
WooCommerce's updated_checkout, updated_wc_div and wc_fragments_refreshed events refresh pricing context. In client mode, this refetches the current catalog and refreshes selected prices across all pages. This adds requests on context refresh, not on each quantity change. A newly detected currency format also invalidates older selected prices. A currency/role plugin with its own AJAX switch event should trigger the following after its server-side currency or customer context has been saved:
document.querySelector('[data-bu-batc-key="wholesale"]')
?.dispatchEvent(new CustomEvent('bu_batc_refresh_estimate'));
Replace wholesale with the form's Connection key. There is no universal currency-switch event across third-party plugins. Prices otherwise remain snapshots until products or pricing context are refreshed; final WooCommerce pricing remains authoritative.
Shipping, taxes, cart fees, coupons, add-on charges and cart-only promotional adjustments are not included. Plugins that only change prices during cart-total calculation are not automatically simulated. Final prices and totals remain authoritative in WooCommerce's cart and checkout. Keep the exclusion note visible and accurate when customizing it.
Unavailable products, incomplete configurations and invalid quantities produce no complete total. The form shows an unavailable/review state instead of presenting a partial total as the full estimate. A pricing request failure clears stale amounts and offers Retry estimate. A failed estimate does not bypass cart validation or prevent an otherwise valid add-to-cart request.
For a quantity/selection-based pricing integration, select Server-side (advanced) and return an authoritative unit price in the store's current currency and the same tax basis as $product->get_price():
add_filter( 'bu_batc_estimate_unit_price', function( $price, $product, $quantity, $selection, $customer ) {
// Apply the same pricing policy as your cart integration, without modifying WC()->cart.
return $price;
}, 10, 5 );
$selection contains all selected product IDs and quantities, and $customer is the current WooCommerce customer. The estimate filter does not change actual cart prices; the pricing extension must apply its policy to the real cart independently. Currency and role extensions must also initialize their pricing context on WooCommerce AJAX endpoints.
Builder previews show empty subtotal placeholders and the estimate band without making pricing requests or implying that demo rows are selected.
Safety and Scope
Required product add-ons and third-party configurations
The element does not automatically render or submit every third-party add-on field. A product with a required engraving, upload, measurement, bundle choice, or other required configuration can fail validation until those choices are made. That is correct: bulk ordering must not bypass required options.
For a known product requiring extra configuration, use the configuration filter below so the row shows View product and links to the product page instead of accepting a quantity. Other eligible rows can still be accepted in the same batch. A universal required-add-on detector is not provided; each plugin stores and validates its requirements differently.
Only published, visible simple products and complete, visible variations are orderable. Grouped, external, and special product types are not included. Hidden/private/draft products cannot be requested by changing browser IDs. Catalog scope is signed, requests use a nonce, prices/attributes come from WooCommerce, and the server revalidates every row.
Variations with an Any ... wildcard need an explicit configuration choice and link to the product page instead. Required add-ons, bundles, measurements, subscriptions, or other custom configurations need their own integration. Their WooCommerce validation rules are not bypassed. Use the following filter to proactively show a product-page link for a product requiring configuration:
add_filter( 'bu_batc_requires_configuration', function( $required, $product ) {
return $required || in_array( $product->get_id(), [ 123, 456 ], true );
}, 10, 2 );
The form displays WooCommerce's current product price HTML; cart rules, taxes, shipping, coupons, and pricing extensions determine final totals. Adding products does not reserve stock. Checkout validates availability again.
Interrupted Requests
A batch carries a unique request ID. The server serializes bulk writes for the customer's cart and caches completed row outcomes for one day. Repeating the same request returns its previous results without adding again. Changing an already-used request is rejected.
After a network interruption, Check request retries that same payload. Editing is locked until the outcome is known. If the server cannot confirm an interrupted operation, review the cart before clearing the selection and starting another batch. This is not a database transaction or a guarantee against every possible infrastructure failure.
Caching and Compatibility
Search and cart actions use WooCommerce AJAX endpoints and current customer context. Do not cache their responses. A stale page nonce produces a refresh-session message. Exclude customer-specific price pages from shared caching where the pricing integration requires it.
The feature uses MySQL/MariaDB named locks for bulk writes. If the host disables named locks, the request fails without adding products. Independent cart-writing plugins still need their own concurrency protection.
Bricks Presentation Controls
Open Presentation on the Bulk Add to Cart element:
- Desktop layout / Mobile layout: choose Table or Compact list independently. Desktop starts at 768px; mobile is 767px and below. Existing elements continue to use tables on both devices.
- Desktop spacing / Mobile spacing: select Comfortable or Compact independently, or inherit the existing Row spacing setting.
- Connection key: enter a unique key such as
wholesaleto connect other elements to this form. Use a different key for each form; a repeated template in a loop must not reuse a key when independent connections are required.
The compact list retains the same product information and ordering behavior. Column labels become inline field labels and quantities remain editable. Result feedback appears below the affected product, without a separate column or Result label, even if Show result column is enabled. Empty feedback occupies no space. Tables also use inline feedback when that option is off. The overall submission summary and per-product report remain available in all layouts. Builder previews use the same presentation without AJAX. No fixed or minimum heights are imposed.
State Messages controls empty, loading, submitting, successful completion, generic error, interrupted-request, and uncertain-request text. Keep %1$s for the accepted product count and %2$s for the failed count in completion messages. Configure both singular and plural completion messages. Empty, Loading, Success, and Error styles each provide typography, background, border, and padding. Server-side validation reasons remain intact so customers can correct individual rows. A partial completion uses the error style and keeps per-row results.
Availability Badges provides shared typography, padding, and borders, plus separate text/background colors for In stock, Out of stock, Backorder, and Choose options. Quantity Buttons provides typography, background, border, padding, hover colors, button width, and disabled opacity. The numeric input width remains in Search and Quantity. These are Bricks CSS controls and can also use Bricks responsive/pseudo-class styling where supported.
Styling reference
| Group or control | Styling scope |
|---|---|
| Heading | Heading typography, background, border, and padding. An empty heading text removes the heading. |
| Table | Table typography, background, border, and width. The table wrapper scrolls horizontally when a table is wider than its container. |
| Table Header | Standard and custom header typography, background, border, and padding. |
| Product Rows | Cell styles, alternate-row background, hover background, selection accent/background, and image size. |
| Search and Quantity | Shared input typography/background/border/padding, focus border, and numeric input width. Filter inputs also use the shared input style. |
| Quantity Buttons | Dedicated plus/minus styling, hover colors, button width, and disabled opacity. Product min/max/increment constraints still determine whether a button is enabled. |
| Availability Badges | Badge typography, padding, borders, and colors for the separate stock/configuration states. Keep text readable instead of relying on color alone. |
| Submit Button | Submit typography/background/border/padding and hover background. Keep a clear label during normal, submitting, and retry states. |
| Secondary Buttons | Review, clear, variation, pagination, quantity-button fallback styles, and filter-reset controls. Dedicated quantity styles can override shared styles. |
| Results | Inline row-result styles and success/error colors. |
| State Messages | Editable state text and separate empty/loading/success/error typography, background, border, and padding. |
| Advanced Filters | Filter-band styling and filter labels; input styling remains shared with Search and Quantity. |
| Custom Columns | Shared custom-cell styling, with row/header styles also applying. |
| Live Estimate | Estimate-band styles, wording, and calculation mode. |
Toolbar gap, Table width, Image size, and Quantity width provide targeted sizing controls. Prefer a compact numeric width when many columns are visible. The plus/minus control is deliberately narrow by default. The component does not impose fixed or minimum heights on product rows; content and padding determine their size.
State-message placeholders
In completion text, %1$s is the accepted product-row count and %2$s is the count needing correction. These are row counts, not the number of units or the cart total. Configure the singular and plural completion messages separately. For example: Added %1$s products; review %2$s items. Preserve placeholder spelling. Per-product server validation reasons remain available even when global summary wording changes.
Live Dynamic Tags
Connect an external counter
- Enter
wholesalein the source form's Presentation > Connection key. - Add a Bricks Basic Text element outside the form.
- Set its text to
Selected products: {bu_batc_count:wholesale}orSelected units: {bu_batc_quantity:wholesale}. - Test on the storefront by selecting quantities and changing result pages. Give every independently connected form a different key.
Insert these tags into the text content of a Bricks Basic Text or similar element:
| Tag | Live value |
|---|---|
{bu_batc_count:wholesale} |
Number of selected product/variation rows |
{bu_batc_quantity:wholesale} |
Total selected units |
{bu_batc_status:wholesale} |
ready, loading, empty, submitting, success, or error |
Replace wholesale with the source form's Connection key. Without a key, a tag uses its containing bulk add-to-cart form, otherwise the first form on the page. Counts include selections on other search-result pages. Accepted rows are removed from the selection and failed rows remain. Before JavaScript initializes, counts are zero and status is ready.
These are browser-updated text tags, not cart totals. Use them in text content, not URLs, HTML attributes, server-side conditions, or queries. They do not persist selections across reloads. The form and its script must be present for live updates.
Events and Bricks Interactions
In an element's Interactions, choose a (BU) Bulk Add to Cart trigger and a normal Bricks action. Bulk add to cart selector optionally limits the source form, for example [data-bu-batc-key="wholesale"] or #brxe-abcdef. Leave it empty to listen to any form.
| Native event | When it fires |
|---|---|
bu_batc_selection_change |
Selected IDs or quantities change |
bu_batc_loading |
A catalog search starts |
bu_batc_loaded |
A catalog search finishes; inspect status for empty/error |
bu_batc_submitting |
A cart request starts, including a retry |
bu_batc_success |
At least one row is accepted, including a partial completion |
bu_batc_error |
A search/request fails or at least one submitted row is rejected |
bu_batc_complete |
A cart request returns row results, including an all-rejected request |
Events bubble from the form. event.detail includes form (DOM element), key, count, quantity, status, and items (selected {id, quantity} entries). Completion also includes the original server payload, accepted, and failed; success/error row events include results and counts where available. Request errors include a message and operation. A network failure emits error, not complete. Success and error can both fire for a partial completion, so use complete for one action per confirmed batch. Events are informational, not permission to trust client prices or bypass WooCommerce validation.
document.addEventListener('bu_batc_complete', function (event) {
if (event.detail.key !== 'wholesale') return;
console.log(event.detail.accepted, event.detail.failed, event.detail.results);
});
Loading events may occur before a late listener is registered. Live tags synchronize current values independently, including when inserted into an AJAX popup.
Practical Setups
Wholesale quick-order page
Create a normal Bricks page, add one Bulk Add to Cart element, and restrict it to the wholesale product range. Use Table on desktop and Compact list on mobile. Show SKU, Price, Availability, and a pack-size custom column. Enable category/brand filters and a client-side estimate. If the page is private, configure the site's access controls and enable Logged-in customers only. A displayed pack size does not enforce a minimum or step; configure quantity rules in WooCommerce or the quantity-rule integration.
Repeat-order catalog
Enable Previously purchased, SKU search, and Availability. Signed-in customers can switch to products from their own paid orders, adjust the new quantities, and add them together. This is a product-history filter, not an exact replay of a previous order: old order prices, coupons, shipping choices, add-on configurations, and quantities are not restored.
Variable-product range
Include the variable parent products. Enable global-attribute filters such as Color and Size. Keep click-to-load for a large catalog, or enable Auto-load variations for a smaller quick-order range. Add an Options column so each child row is distinguishable. Use a complete purchasable variation, not an Any-attribute wildcard, for direct bulk addition.
Popup or off-canvas ordering
Place the element inside the intended Bricks popup or off-canvas content and give it a unique Connection key. Use a layout appropriate to the panel width; a narrow desktop side panel may also benefit from Compact list. Test first open, AJAX content loading, repeated opening, quantity editing, and the cart update. Third-party popup implementations need their own asset-loading verification. Avoid duplicating the same connection key across multiple rendered copies.
Troubleshooting
| Symptom | Check |
|---|---|
| Element is missing in Bricks | Activate WooCommerce and BricksUltimate, enable Bulk Add to Cart in Woo Elements, save, and reopen the builder. |
| Builder shows only five products or inputs are disabled | This is the intended read-only preview. It ignores frontend catalog restrictions. Test the actual catalog and ordering on the storefront. |
| No products found | Check Include/Exclude, category IDs, publication/catalog visibility, stock visibility, active filters, and customer-only access. Clear search and filters independently. |
| Search or filters cannot load | Inspect the WooCommerce AJAX response, stale nonce/session messages, caching, security rules, and JavaScript errors. Use Retry filters when dropdown options fail to load. |
| Brand or attribute dropdown is missing | Choose a registered public brand taxonomy and global filter attributes. A brand filter with no valid taxonomy, or an attribute filter with no configured attributes, is omitted. |
| Some taxonomy options are missing | Only up to 200 non-empty terms are loaded per dropdown. Category options also respect configured category restrictions. Local text attributes cannot be used as filter taxonomies. |
| Price filter differs from the estimate | The filter uses stored catalog lookup prices; estimates exclude tax and may use customer pricing filters. Currency/role integrations need a consistent catalog-bound conversion. |
| Previous purchases are empty | Sign in as the actual order customer. Verify paid order status, exact purchased variation IDs, current product visibility and configured catalog scope. Guest orders are not matched by email. |
| Custom column is missing or empty | Enter a heading, valid attribute/field key, and a scalar value. Protected fields are blocked by default. Check parent fallback and the twelve-column limit. |
| Quantity is rejected or its button is disabled | Check minimum, maximum, step, stock, sold-individually rules, request-state locks, and required product options. Zero deselects the row. |
| Estimate is unavailable | Correct quantities, review product availability/options, and retry. Client mode needs supplied numeric price snapshots; advanced pricing may require server mode and an integration. |
| Estimate is different from checkout | It excludes tax, shipping, coupons, fees, add-on charges and cart-only pricing changes. WooCommerce's current cart/checkout totals are authoritative. |
| A required add-on product is rejected | Configure it on its product page or implement a specific integration. Use the required-configuration filter to offer a product-page link proactively. |
| Some rows were added and some failed | This is intentional partial acceptance. Accepted rows clear; failed rows keep their quantities. Review the report above the table and correct only the failed rows. |
| A request was interrupted | Use Check request for the same payload. If the outcome cannot be confirmed, review the actual cart before clearing the selection or creating a new batch. |
| Mini-cart did not refresh | Check the WooCommerce fragments/event bridge and any custom mini-cart or checkout extension. Do not cache WooCommerce AJAX responses. |
| Controls remain locked | An add request or its outcome may be unresolved. Follow the retry/cart-review message instead of forcing another submission. |
| Changes to styling do not appear | Regenerate Bricks CSS, clear relevant caches, and inspect instance/class-specific overrides. Check both configured presentation modes. |
Frequently Asked Questions
Does it add all selected pages or only the current page?
All selections within the same rendered element are submitted, including rows hidden by search, filters, or pagination. Selected items provides a complete review. Separate form instances do not combine their selections.
Can customers resume a selection after reloading the page?
No. Selections are held in the browser for that rendered instance and do not persist across page reloads. Products already accepted into the WooCommerce cart follow WooCommerce's normal cart/session behavior.
Does it replace checkout or guarantee the displayed estimate?
No. It prepares a multi-product cart addition. Final prices, stock checks, required options, fees, shipping and taxes are handled by WooCommerce and its active integrations.
Are client-side estimates safe?
They are informational. The browser can modify its displayed estimate, but actual additions use server-side WooCommerce prices and validation. Numeric prices come from the server, not from parsed display HTML.
Can every third-party add-on or pricing plugin work automatically?
No universal integration is promised. Standard add-to-cart validation hooks run, so plugins can enforce their rules, but their fields and cart-only calculations are not automatically reproduced inside the table. Test the actual plugin combination and use a specific integration or product-page configuration link where necessary.
Does pack size enforce multiples or delivery text calculate shipping?
No. These columns display approved text/values only. Quantity-rule integrations enforce pack increments; WooCommerce and shipping integrations calculate actual shipping services and charges.
Technical Reference
The Bricks element identifier is bu-bulk-add-to-cart. CSS classes and data attributes use bu-batc; events and dynamic tags use bu_batc_. The JavaScript initializer is buBulkAddToCart. Element control keys use batc, and the Woo Elements activation setting is bulkaddtocart.
Primary files are includes/Elements/WooBulkAddToCart.php, includes/WooCommerce/BulkAddToCart.php, includes/WooCommerce/BulkAddToCartCatalog.php, assets/css/elements/bulk-add-to-cart.css, and assets/js/elements/bulk-add-to-cart.js.
The WooCommerce AJAX actions are bu_batc_search, bu_batc_filters, bu_batc_add, and bu_batc_estimate. They use a nonce and signed element configuration. Do not expose arbitrary metadata, trust client-submitted prices, or replace cart validation with a successful estimate. The configuration, estimate-price, protected-field approval and catalog-price conversion hooks are documented in the corresponding sections above.
Storefront Test Checklist
- Search by a simple SKU and by a variation SKU.
- Combine category, brand, attribute, price and stock filters; clear filters and verify selections remain.
- Test previous purchases as a guest, a customer with paid orders, and a customer without qualifying orders.
- Select quantities across two pages and review them with Selected items.
- Check WooCommerce minimum/maximum/increment rules, zero deselection, backorders and unavailable products.
- Verify custom columns on simple products and variations, including empty values, parent fallback and protected-field blocking.
- Check both estimate modes where used, currency formatting and pricing-context refreshes. Confirm the exclusion note remains accurate.
- Submit a batch with both an eligible row and an intentionally invalid row; verify only the accepted quantities reach the real cart.
- Test the mini-cart, cart and checkout integrations, including the store's actual third-party add-ons/pricing plugins.
- Check desktop/mobile layouts, keyboard controls, popup placement and reduced-motion behavior before making the page public.