Mobile Filters

On mobile devices, FilterIQ displays filters in a slide-out drawer instead of a sidebar. This provides a touch-friendly filtering experience optimized for small screens.

How the Mobile Drawer Works

The mobile drawer (mobile-drawer.js) activates automatically on screens narrower than 768px. It replaces the desktop sidebar with a full-height panel that slides in from the left or right edge.

Opening and Closing

• Open: Shoppers tap the "Filters" button that appears above the product grid
• Close: Tap the X button, tap the overlay backdrop, or swipe the drawer closed
• Scroll lock: When the drawer is open, background page scrolling is disabled to prevent accidental interactions

Gestures

The drawer supports touch gestures for a native-feeling experience:

• Swipe to close -- Swipe the drawer toward its origin edge to dismiss it
• Scroll within drawer -- Vertical scrolling works naturally inside the drawer when filter options overflow

Layout Configuration

You can choose the drawer as your default filter layout (even on desktop) or let it activate only on mobile. Configure this in Filters > Presets > Layout Presets.

Container Options

Layout presets support three container types:

• sidebar -- Traditional vertical filter panel
• toolbar -- Horizontal filter bar above the grid (maps to "horizontal" in the storefront)
• drawer -- Slide-out drawer panel

Touch Targets

All interactive elements in the mobile drawer meet WCAG 2.1 AA touch target requirements:

• Filter checkboxes and radio buttons: minimum 44x44px touch area
• Color swatches: minimum 44x44px touch area
• Price range slider handles: 44x44px
• Close button: 44x44px
• Clear/Apply buttons: full-width, 48px tall

Accessibility

The mobile drawer is built with accessibility as a core requirement:

• Focus trap: When the drawer opens, focus is trapped inside it. Tab and Shift+Tab cycle through interactive elements within the drawer only
• Focus restoration: When the drawer closes, focus returns to the element that triggered it (the "Filters" button)
• Screen reader announcements: Opening and closing the drawer triggers ARIA live region announcements
• Escape key: Pressing Escape closes the drawer
• Reduced motion: When the user has prefers-reduced-motion: reduce enabled, the drawer appears instantly without slide animation

Filter Counts and Apply Behavior

Live Counts

As shoppers select filter options in the drawer, product counts update in real-time to show how many products match the current selection. This helps shoppers understand the impact of their filters before applying.

Apply Button

The mobile drawer includes a prominent "Show X Results" button at the bottom. Depending on your configuration:

• Auto-apply (default: off) -- Filters apply immediately as options are selected. The "Apply" button acts as a close button
• Manual apply -- Filters only apply when the shopper taps "Show Results." This reduces API calls and provides a better experience on slow connections

Configure auto-apply behavior in Filters > Presets > Config Presets.

Performance

• The mobile drawer JS is loaded asynchronously and only initializes on mobile viewports
• Per-instance state tracking prevents double-mounts (important for Shopify themes that re-render sections)
• Instance IDs are generated with crypto.randomUUID() with a Safari fallback for older iOS devices
• Body scroll lock uses a saved scroll position to prevent content jumping

Troubleshooting

Drawer does not open

• Verify the Theme App Extension is enabled
• Check that your theme does not have conflicting position: fixed or z-index styles
• Look for [SSF:drawer] messages in the browser console (enable debug mode: window.SSF.debug = true)

Filters button does not appear on mobile

• The "Filters" button is rendered by the theme extension when it detects a collection page
• Ensure your collection template includes the standard Shopify collection object
• Try viewing the /collections/all page as a baseline test