Category Slider Widget

1. Installation

For complete installation instructions, please refer to the separate Jscriptz Subcats Installation Guide, which covers:

• System requirements
• Installation via Adobe Commerce Marketplace
• Installation via Composer (CLI)
• Verification steps
• Uninstallation and upgrade instructions

2. Global Configuration

After installation, configure the global Subcats behavior. These settings serve as defaults that can be overridden at the category or widget level.

Configuration overview showing the JSCRIPTZ section with all collapsible sections

2.1 General Settings

The General Settings section controls the core module behavior.

General Settings panel showing Enabled, Open Links In, Hide Empty Categories, and Show Product Count options

2.2 Design & Layout

The Design & Layout section controls the overall appearance and responsive behavior of your subcategory cards.

Column Options Available: 1 Column, 2 Columns, 3 Columns, 4 Columns, 5 Columns, 6 Columns

Design & Layout configuration panel showing all layout options

2.3 Card Design

The Card Design section provides extensive customization options for the appearance of each subcategory card.

Theme & Appearance

Card Hover Effects

Image Settings

Card Design configuration panel showing Theme Preset, card styling options, hover effects, and image settings

2.4 Card Title Design

Customize how category names appear on each card.

Card Title Design configuration panel showing title color, font size, weight, alignment, and font stroke options

2.5 Description Design New in 2.2.0

Control how category descriptions appear on subcategory cards.

2.6 Theme Presets

Jscriptz Subcats includes several built-in Theme Presets that provide pre-configured styling combinations.

Available Theme Presets

How to Use Theme Presets

1. Navigate to Stores → Configuration → JSCRIPTZ → Jscriptz Subcats
2. Expand the Card Design section
3. Find the Theme Preset dropdown at the top of the section
4. Select your desired preset
5. The fields below will update with the preset values
6. Click Save Config
7. Flush cache: bin/magento cache:flush

2.7 Custom Theme Presets New in 2.2.0

Version 2.2.0 introduces the ability to save your own custom theme presets for quick reuse across your store.

Saving a Custom Preset

1. Configure your desired design settings in the Card Design section
2. Scroll to find the "Save Theme As..." button
3. Click the button to open the save dialog
4. Enter a name for your preset (e.g., "Holiday Theme", "Summer Sale")
5. Click Save
6. Your preset will appear in the Theme Preset dropdown

Card Design section showing Theme Preset dropdown and "Save theme as..." button with preset count indicator

Managing Custom Presets

What Gets Saved in a Custom Preset

Each custom preset stores all 25+ design fields including:

• Card styling (radius, border, padding, background, shadow)
• Card hover effects (shadow, scale, background)
• Image styling (border, radius, aspect ratio)
• Image hover effects (shadow, scale)
• Title styling (font size, weight, color, alignment, stroke)
• Description styling (font size, color, max lines, visibility)
• Content padding and transition duration

3. Category-Level Setup

This is where the magic happens. At the category level, you define which subcategories appear, in what order, and how they look. These settings override the global defaults when specified.

3.1 Enable Subcats on a Category

To configure Subcats for a category:

1. Go to Catalog → Categories
2. Select the parent category where you want subcategory cards to appear (e.g., Women, Men, Gear, Training)
3. In the left-side tabs, find and click the Jscriptz Subcats tab

Category edit page showing the Jscriptz Subcats tab in the left sidebar with configuration options

Jscriptz Subcats Tab Fields

3.2 Upload Subcategory Images

Each subcategory card can have its own dedicated image, providing visual consistency across your store.

1. In Catalog → Categories, select the child category (the one that will appear as a card)
2. Open the Jscriptz Subcats tab
3. Find the Subcat Image field
4. Click Upload and select your image
5. Save the category

Image Fallback Behavior

The module uses an intelligent fallback system to ensure cards always have images:

3.3 Subcategory Order & Selection

On the parent category, you can precisely control which subcategories appear and in what order.

1. Select the parent category (e.g., "Tops")
2. Open the Jscriptz Subcats tab
3. In the Subcategories to Display field, you'll see a multi-select list of all child categories
4. Select the categories you want to show as cards
5. Use the ↑ and ↓ arrows to reorder the selected subcategories
6. Leave empty to show all active child categories
7. Save the category

Subcategories to Display multi-select showing selected categories with up/down ordering arrows

3.4 Per-Category Column Overrides

You can override the global column settings for specific categories. This is useful when different categories have different numbers of subcategories.

4. Using the CMS Widget

Jscriptz Subcats can be rendered on any CMS page or static block using the bundled widget. This gives you complete flexibility to display subcategory cards anywhere on your site — home pages, landing pages, promotional blocks, and more.

4.1 Add Widget to a CMS Page

1. Go to Content → Pages
2. Edit the page where you want to add subcategory cards (e.g., Home Page)
3. In the Content section, click Edit with Page Builder (or access the WYSIWYG editor)
4. Position your cursor where you want the widget, or add a new row
5. Click the Insert Widget button (looks like a cookie/chip icon in the toolbar)
6. In the Insert Widget dialog, select Widget Type: Jscriptz Subcats
7. Configure the Widget Options (see next section)
8. Click Insert Widget
9. Save the page

Page Builder interface with the editing toolbar

Click the "Insert Widget" button (cookie icon) in the toolbar to add a widget

The Edit Widget dialog with Jscriptz Subcats selected showing all configuration options

4.2 Widget Options Explained

When inserting a Jscriptz Subcats widget, you have extensive configuration options:

Basic Options

Category Selection

Display Options

Title Styling Options

Card Title & Description Options New

Card & Image Design Options New

All card design options from the global configuration are also available at the widget level:

• Image Aspect Ratio
• Image Corner Radius, Border
• Image Hover Shadow & Scale
• Card Corner Radius, Border, Padding, Background, Shadow
• Card Hover Shadow, Scale, Background
• Content Padding
• Design Preset override

4.3 Slider Template New in 2.2.0

Version 2.2.0 introduces a Slider Template option that displays your subcategory cards in a horizontal carousel format instead of a static grid.

Enabling the Slider

1. When configuring the widget, find the Template dropdown in Main Settings
2. Select Subcats Slider instead of "Subcats Grid"
3. The Slider Settings section will appear with additional options
4. Configure slider behavior as needed
5. Save the widget

Slider Settings

Responsive Slides Per View

Control how many category cards are visible at once on different screen sizes:

Slider Behavior

• Navigation Arrows: Previous/Next buttons appear on the left and right sides of the slider. They are automatically disabled at the start/end when loop is off.
• Pagination Dots: Clickable dots below the slider indicate the current page and allow direct navigation.
• Touch/Swipe: On mobile devices, users can swipe left/right to navigate between slides.
• Autoplay Pause: When a user hovers over the slider (desktop) or touches it (mobile), autoplay automatically pauses to prevent disruption.
• Keyboard Navigation: Arrow keys can be used to navigate when the slider is focused.

4.4 Use in a CMS Block

You can also add Jscriptz Subcats to a reusable CMS Block, which can then be placed in multiple locations.

1. Go to Content → Blocks
2. Click Add New Block or edit an existing block
3. Give the block a meaningful Title and Identifier (e.g., "Jscriptz Subcats Block")
4. In the Content area, click Edit with Page Builder or use the WYSIWYG
5. Insert the Jscriptz Subcats widget using the same process as CMS pages
6. Save the block

4.5 Add CMS Block to Category

You can display your Jscriptz Subcats CMS Block directly on a category page using the Add CMS Block feature.

1. Go to Catalog → Categories
2. Select the category where you want to display the block
3. Scroll down to find the Content section
4. Find the Add CMS Block dropdown
5. Select your Jscriptz Subcats Block
6. Save the category

Benefits of this approach:

• Create one reusable block with your widget configuration
• Apply it to multiple categories
• Update the block once, and all categories reflect the change

5. Creating a Standalone Widget

In addition to inserting widgets into CMS pages and blocks, you can create standalone Widget Instances that can be assigned to specific layout containers and pages.

1. Go to Content → Widgets
2. Click Add Widget
3. In the Settings panel:
   • Type: Select Jscriptz Subcats
   • Design Theme: Select your active theme
4. Click Continue
5. Configure Storefront Properties (Widget Title, Store Views, Sort Order)
6. Configure Layout Updates to specify where the widget appears
7. Configure Widget Options (same as when inserting via Page Builder)
8. Click Save

The Content > Widgets page listing all widget instances

Step 1: Select "Jscriptz Subcats" as Type and choose your Design Theme, then click Continue

Storefront Properties: Configure Widget Title, Store Views, Sort Order, and Layout Updates

Widget Options: Configure categories, theme preset, columns, titles, and design settings

6. Image & Layout Behavior

6.1 Card Structure

Each subcategory card typically displays:

• Category Image — The visual centerpiece of the card
• Category Name — The title/label for the subcategory
• Product Count Badge — Optional count of products (if enabled)
• Optional Description — Controlled by description design settings
• Hover Effects — Shadows and scale effects on interaction

6.2 Image Fallback Chain

Jscriptz Subcats uses an intelligent image fallback system:

1. Subcat Image — Custom image uploaded in the Jscriptz Subcats tab (highest priority)
2. Category Image — Standard Magento category image from the Content tab
3. Product Image — A product image from within that category (if enabled in global settings)

6.3 Image Aspect Ratio New in 2.2.0

Control how images are displayed using the Image Aspect Ratio setting:

6.4 Responsive Columns

The column system adapts to different screen sizes:

7. Frontend Card Layout

7.1 Grid Display

The standard grid layout displays subcategory cards in a responsive row/column format.

Frontend display showing subcategory cards with images and category names

Each card includes:

• A prominent image
• The category name below
• Optional product count badge
• Optional description (respecting max lines setting)
• Smooth hover transitions (if enabled)
• A clickable area that links to the subcategory page

7.2 Category Page Integration

When configured on a category, the subcategory cards appear above the product listing, providing intuitive navigation for customers to drill down into specific product types.

Category page showing subcategory cards displayed for customer navigation

7.3 Mobile Responsive View

On smaller screens, the layout automatically adjusts:

• Cards stack appropriately for the screen width
• Touch-friendly sizing
• Readable text and imagery
• Good Largest Contentful Paint (LCP) scores for Core Web Vitals

Mobile responsive view showing subcategory cards adapted for smaller screens

8. Hyvä Theme Compatibility

Jscriptz Subcats is fully compatible with Hyvä Themes, the modern AlpineJS/Tailwind CSS-based Magento theme.

8.1 Theme Detection

The module includes intelligent theme detection that automatically:

• Detects when Hyvä is active
• Loads the appropriate templates and styling
• Uses Tailwind CSS utilities when appropriate

8.2 Hyvä-Specific Configuration

When using Hyvä, the module respects Hyvä's architecture by:

• Using AlpineJS for interactivity
• Leveraging Tailwind CSS for styling
• Maintaining compatibility with Hyvä's performance optimizations

8.3 Live Demo

Visit https://hyva.jscriptz.com to see Jscriptz Subcats running on a Hyvä theme installation.

9. Troubleshooting

9.1 No Subcategories Showing

Check the following on the parent category:

• Is the Jscriptz Subcats module Enabled globally? (Stores → Configuration → JSCRIPTZ → Jscriptz Subcats → General Settings → Enabled = Yes)
• Have you selected any subcategories in Subcategories to Display? If left empty, all active children should show.

Check the child categories:

• Is Display this Subcategory? set to Yes (or not explicitly set to No)?
• Is the child category Enabled and assigned to the correct Store View?
• If Hide Empty Categories is enabled, does the category have products?

After making changes:

bin/magento indexer:reindex
bin/magento cache:flush

9.2 Widget Appears But No Styling

If you see basic HTML with no card styling:

1. Verify CSS is loading: Check that your theme is including Jscriptz Subcats CSS
2. Deploy static content: bin/magento setup:static-content:deploy -f
3. For Hyvä themes: Ensure the Hyvä-specific layout XML is active
4. Clear all caches: bin/magento cache:flush

9.3 Images Not Displaying

1. Check image upload: Verify the Subcat Image is uploaded in the category's Jscriptz Subcats tab, or ensure the standard Category Image is set
2. Check fallback settings: If relying on product image fallback, ensure Use Product Image Fallback is enabled globally
3. Check file permissions: Ensure pub/media/catalog/category/ is writable

9.4 Custom Presets Not Saving

1. Check preset limit: You can only save 10 presets per store view
2. Check permissions: Ensure your admin user has the Jscriptz_Subcats::preset_manage ACL permission
3. Check JavaScript console: Look for any JavaScript errors in the browser console
4. Verify database: Check that the jscriptz_subcats_custom_preset table exists

Quick Reference: Configuration Hierarchy

Understanding the configuration override cascade helps troubleshoot unexpected behavior:

Widget Settings (highest priority)
       ↓
Category Settings
       ↓
Global Configuration (lowest priority)

For example, if you set Desktop Columns to 4 globally, but a specific widget sets Desktop Columns to 3, that widget will display 3 columns.

Support

For additional help or to report issues: