Modern Checkbox Pro User Guide

Getting Started

Modern Checkbox Pro automatically converts checkboxes into sleek toggle switches on your product pages. It gives you complete control over which options appear based on customer selections, creating a smoother shopping experience.

What Modern Checkbox Pro Does

• Visual Enhancement: Replaces standard checkboxes with modern, polished toggle switches that match your store design.
• Smart Visibility: Show or hide form fields based on which toggles customers select.
• Form Preservation: Maintains all form functionality—selections still work exactly as they did before, just with better visuals.
• Easy Setup: Configure everything from our simple admin dashboard with no coding required.

1. Create Mappings (Basic Mode)

Mappings connect a checkbox to the field you want to show or hide. When a customer toggles the checkbox on, the linked field appears. When toggled off, it disappears.

Step-by-Step Setup

1. Open the Modern Checkbox Pro app from your BigCommerce admin.
2. Click the Add Mapping button.
3. Enter the Checkbox Label exactly as it appears on your product page (e.g., "Add Gift Wrap", "Include Insurance").
4. Enter the Target Field Label (the field you want to show/hide when this checkbox is toggled, e.g., "Gift Message", "Insurance Amount").
5. Click Save Changes.
6. Go to your product page and refresh to see the toggles in action.

Example Scenarios

• Gift Options: Checkbox labeled "Gift Wrap" shows/hides "Gift Message" text field.
• Customization: Checkbox labeled "Monogramming" reveals "Monogram Text" input.
• Service Add-ons: Checkbox labeled "Priority Shipping" opens "Delivery Date Picker".

2. Visibility Behavior & Logic

Modern Checkbox Pro uses simple toggle logic: when a customer checks the box (toggles ON), the target field appears. When unchecked (toggles OFF), it hides.

Important Behavior Notes

• Visibility Only: Hiding a field removes it from view but does NOT clear any data the customer entered. If they toggle a field off and back on, their input remains.
• Multiple Targets: You can create multiple mappings from different checkboxes to different fields on the same product.
• Form Validation: Hidden fields are not required by default. Your form validation rules apply as normal.
• Mobile Compatibility: Toggles work perfectly on mobile, tablet, and desktop—the visibility logic adapts to all screen sizes.

3. Styling & Customization

Customize toggle appearance to match your brand. Modern Checkbox Pro offers pre-built presets and granular controls.

Color Presets

• Primary: Modern blue with crisp contrast. Best for tech and contemporary brands.
• Ocean: Bright teal with soft glow. Perfect for fresh, friendly aesthetics.
• Midnight: Dark slate for premium, luxury brands.
• Custom: Choose your own colors for exact brand matching.

Size & Shape Options

• Size: Small (compact), Medium (balanced), or Large (prominent). Choose based on how much attention you want toggles to receive.
• Shape: Rounded (modern, approachable) or Squared (minimalist, professional).
• Animation: Toggles animate smoothly when clicked, providing nice visual feedback.

How to Apply Styling

1. Open the Modern Checkbox Pro app.
2. Go to the Styling tab.
3. Choose your preset or customize colors.
4. Select size and shape preferences.
5. Click Save Changes.
6. Refresh your product page—changes apply instantly across all toggles.

4. Advanced Mode (For Complex Layouts)

Sometimes product fields are nested inside groups, use custom HTML structures, or have hidden labels. Advanced Mode lets you target these complex scenarios using CSS selectors and attribute matching.

When to Use Advanced Mode

Use Advanced Mode when Basic Mode doesn't work. Common cases include:

• Option labels that appear inside collapsible groups or tabs.
• Fields generated by third-party apps (like date pickers, custom builders).
• Options without visible labels or with hidden text.
• Checkboxes inside custom product configurators.
• Fields identified by placeholder text instead of labels.

How Advanced Mode Works

Instead of matching visible labels, Advanced Mode matches elements using:

• CSS Class Names: Targets elements with specific class attributes.
• Element IDs: Unique identifiers assigned to form fields.
• Placeholder Text: Text hints inside input fields.
• Attribute Values: Any custom HTML attributes on elements.
• DOM Position: Hierarchical relationships in the page structure.

Step 1: Gather the Data You Need

To use Advanced Mode, you need to identify two things:

1. The Checkbox to Watch: Identify what checkbox should trigger visibility.
2. The Target Element: Identify what field should appear/hide.

You'll find this data using your browser's Developer Tools (DevTools). Here's how:

Step 2: Open Browser Developer Tools

• Google Chrome, Edge, Firefox: Right-click anywhere on the product page and select Inspect or press F12.
• Safari: Enable Developer Tools in Preferences, then right-click and select Inspect Element.

Step 3: Find the Checkbox Identifier

1. In DevTools, click the Inspect/Select Element button (usually a cursor icon in the top-left).
2. Click on the checkbox you want to trigger the mapping.
3. DevTools will highlight the checkbox element in the code.
4. Look for one of these attributes:
   • id="some-id" — The unique ID (easiest to use).
   • class="some-class" — One or more class names.
   • data-attribute="value" — Custom data attributes.
   • Nearby text like <label>Gift Wrap</label> — The label text.
5. Copy the identifier (right-click the element and select Copy → Copy selector).

Example: You want to find the checkbox labeled "Add Gift Wrap". In DevTools, you might see:

<input type="checkbox" id="gift-wrap-checkbox" name="gift_wrap">
<label for="gift-wrap-checkbox">Add Gift Wrap</label>

The identifier is: id="gift-wrap-checkbox" or the CSS selector #gift-wrap-checkbox

Step 4: Find the Target Field Identifier

1. In DevTools, click the Inspect/Select Element button again.
2. Click on the field that should appear/hide (the target).
3. Look for identifying attributes: id, class, name, or nearby labels.
4. Copy the selector (right-click → Copy → Copy selector).

Example: Your target is a text field for "Gift Message". You might see:

<input type="text" id="gift-message-input" placeholder="Enter your message">
<label for="gift-message-input">Gift Message</label>

The identifier is: id="gift-message-input" or the CSS selector #gift-message-input

Step 5: Configure Advanced Mode in the App

1. Open the Modern Checkbox Pro app.
2. Click Add Mapping.
3. Instead of using Basic Mode, select the Advanced Mode toggle.
4. In the Checkbox Selector field, paste the CSS selector or identifier you found for the checkbox.
   • If you have an ID, use: #gift-wrap-checkbox
   • If you have a class, use: .checkbox-label-gift-wrap
   • If you have a complex path, paste the full selector from DevTools.
5. In the Target Selector field, paste the CSS selector for the field that should show/hide.
   • If you have an ID, use: #gift-message-input
   • Or match by attribute: input[placeholder="Enter your message"]
6. Click Save and Test.
7. Go to your product page, and toggle the checkbox on/off to verify the target field appears and hides correctly.

Common Advanced Mode Selectors

Scenario	Selector Example
Match by ID	#my-checkbox-id
Match by class	.custom-class-name
Match by placeholder	input[placeholder="Gift Message"]
Match by data attribute	[data-field-id="gift-wrap"]
Match by element and attribute	input[type="text"][name="gift_message"]

Troubleshooting Advanced Mode

• Selector Not Working: Double-check the selector in DevTools. Click the selector in DevTools' Console to verify it still matches the right element.
• Target Not Found: The selector might be too specific or the element structure might have changed. Try a simpler selector that matches the element's class or ID.
• Works Sometimes: Some product pages load content dynamically. This happens with add-on apps or custom builders. Contact support for advanced troubleshooting.

5. Catalyst Date Picker Fields (Advanced)

BigCommerce Catalyst storefronts use custom date picker implementations that often hide the underlying structure from basic selectors. When you hide a Catalyst date field, the date picker input might disappear but the label stays visible—or vice versa. This section shows you how to handle this.

Why Simple Selectors Don't Work

Catalyst date pickers are typically wrapped in custom containers with classes like relative, overflow-hidden, rounded-lg, and border. The actual input is inside this wrapper, and it's often identified by a numeric name attribute rather than an ID. Because of this layered structure:

• Hiding just the input leaves an empty box visible
• Hiding just the wrapper leaves the label floating
• Generic selectors hide too many fields at once

Solution: Combined CSS Selectors

Use Advanced Mode with a combined selector that targets both the label and the date picker container. Here's a real example:

HTML Structure (from your Catalyst store):

<label for="_r_6_">Delivery Date</label>
<div class="relative overflow-hidden rounded-lg border">
  <input type="text" name="113" class="flatpickr-input">
</div>

Working Selector:

label:has(+ div input[name="113"]), div.relative.overflow-hidden.rounded-lg.border:has(input[name="113"])

What This Does:

• First part (label:has(+ div input[name="113"])): Hides the "Delivery Date" label
• Second part (div.relative.overflow-hidden.rounded-lg.border:has(input[name="113"])): Hides the date picker wrapper
• Result: Both label and input disappear together, creating a clean hidden state

Step-by-Step Guide to Find Your Selector

1. Open the storefront product page in your browser
2. Right-click the date field label and select Inspect
3. Examine the HTML structure to find:
   • The label text (should match your field label)
   • The wrapper div classes (usually relative overflow-hidden rounded-lg border)
   • The input's name attribute (e.g., name="113")
4. Copy the number from the input's name attribute (e.g., 113)
5. Replace the example number in the selector with your number
6. Open Modern Checkbox Pro and select Advanced Mode
7. Paste your custom selector into the Field Selector field
8. Save changes and test on the product page

Important Notes

• If only the date picker hides: Include the label selector from the combined example
• If only the label hides: Include the div selector from the combined example
• If too many fields hide: Your selector is too broad—use the exact numeric name to be specific
• Dynamic IDs: IDs like _r_6_ may change on refresh, so always use the name attribute instead
• Different wrapper classes: Some Catalyst stores use different CSS classes. Adapt the selector by including the exact classes from your inspector

6. Troubleshooting & FAQ

Toggles Don't Appear on My Product Page

• Check Installation: Verify Modern Checkbox Pro is installed and enabled in your BigCommerce admin.
• Clear Cache: Your browser cache might be outdated. Clear cookies and cache, then refresh.
• Wait for Propagation: Sometimes it takes a few minutes for changes to appear across all product pages.
• Check Product Type: Ensure your product has checkboxes or custom options. Digital products or simple products might not show options.

Mapping Created But Toggle Doesn't Work

• Label Mismatch: The checkbox label or target field label might have slight differences (spaces, capitalization, punctuation). Go to your product page, copy the exact text, and paste it into the app.
• Try Advanced Mode: If the labels match but the mapping still doesn't work, the field structure might be complex. Use Advanced Mode with the steps above.
• Save Changes: After creating a mapping, click Save Changes and wait a few seconds before testing on the product page.

Target Field Not Showing/Hiding Reliably

• Browser DevTools Check: Open DevTools and check for JavaScript errors (the red circle in the Console tab). If errors appear, they might be blocking visibility logic.
• Conflicting Apps: Another product customization app might be interfering. Temporarily disable other apps to test.
• Custom Theme Issue: Some custom themes have unusual DOM structures. Contact support with your theme name for assistance.

Styling Isn't Showing Correctly

• Save Changes & Refresh: Always click "Save Changes" and wait 5 seconds before refreshing the product page.
• Hard Refresh: Press Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) to bypass browser cache.
• Check Multiple Products: Styling applies globally. Open a different product page to confirm the changes took effect everywhere.

Toggles Work on Desktop But Not Mobile

• Responsive Design: Modern Checkbox Pro is fully responsive. If it's not working on mobile, there might be a theme compatibility issue.
• Mobile Cache: Clear your mobile browser's cache and cookies, then refresh.
• Test Across Devices: Try a different mobile device (iOS vs Android) to isolate the issue.

Extra Visibility Options Are Showing That Shouldn't Be

• Multiple Matches: If multiple fields match your target selector (especially in Advanced Mode), all of them might appear/hide together. Review your target selector and make it more specific.
• Check Related Mappings: You might have multiple mappings affecting the same field. Review all mappings to find conflicts.

Advanced Mode Selector Isn't Working

• Verify Selector Syntax: Test your selector in the browser Console: Open DevTools, go to Console tab, type document.querySelector('YOUR-SELECTOR-HERE'), and press Enter. If it returns null, the selector doesn't match anything.
• Dynamic Content: Some product pages load content dynamically (after a delay). If the element doesn't exist when the app loads, Advanced Mode might not find it.
• Whitespace and Special Characters: CSS selectors are case-sensitive. Make sure IDs and class names match exactly, including spaces and hyphens.

7. Best Practices

Naming Conventions

• Use clear, descriptive labels for your checkboxes and fields.
• Match checkbox labels to what customers see on your product page.
• Keep labels short and simple to reduce labeling errors.

Performance Tips

• Mappings execute instantly with zero performance impact.
• You can create unlimited mappings without slowing down your store.
• Toggles are lightweight and render faster than the products they're on.

Accessibility

• Modern Checkbox Pro maintains full keyboard navigation support.
• Toggles work with screen readers and accessibility tools.
• All visibility changes are announced to assistive technologies.

Testing Your Setup

• Always visit your product page after making changes.
• Test on both mobile and desktop.
• Toggle every checkbox multiple times to confirm visibility logic.
• Test on different browsers to catch compatibility issues early.