A developer guide to the current JavaScript modules, WordPress loading paths, DOM contracts, and responsive behavior in IM Base.

Overview

IM Base uses native JavaScript without external front-end frameworks. Front-end modules are stored in assets/js and cover headers, drawers, dropdowns, page-top controls, scrolling, the table of contents, animations, parallax, and sidebar behavior. The separate admin module, assets/js/admin/theme-settings.js, supports theme-settings interactions such as conditional fields, WordPress Media Library controls, and shortcode copying.

JavaScript depends on established imb- selectors and data attributes, along with existing ARIA, keyboard, focus, and Escape-key behavior. Responsive breakpoints must be read from window.imbResponsiveSettings rather than hardcoded, and state and inline styles must be reset when responsive modes change. Preserve responsive behavior, reduced-motion behavior, and the existing DOM contracts when modifying templates, styles, or scripts.

Front-end JavaScript Files

The front-end files include header.js, which hides or shows .imb-header and .imb-mobile-nav during scrolling and uses the localized imbHeaderSettings and imbResponsiveSettings values. drawer.js coordinates .imb-drawer-button, .imb-header-nav, .imb-sidebar, .imb-overlay, and .imb-body, updating ARIA state and using localized drawer labels where available. dropdown.js manages .imb-header-item and .imb-header-menu__sub interactions: hover and focus on tablet and desktop, and tap-driven height animation on mobile; it depends on localized responsive breakpoints. sidebar-sticky.js calculates the desktop sidebar boundary and writes the –imb-sidebar-sticky-top custom property.

page-top.js connects page-top controls with the document and the scrollable .imb-sidebar, .imb-header-nav, and .imb-toc-drawer panels, scrolling the active container to its top. scroll-animation.js reveals .imb-animate elements with IntersectionObserver, or immediately when reduced motion is preferred or the API is unavailable, and sets –imb-animation-duration and –imb-animation-distance. parallax.js updates the –imb-parallax-y custom property for visible .imb-parallax elements and disables the effect for reduced motion.

smooth-scroll.js handles same-page fragment links other than TOC links, reading the fixed-header offset from the –imb-scroll-offset custom property and honoring reduced-motion preferences. table-of-contents.js can build TOC markup in its client-side placeholders, animates .imb-toc-details, scrolls .imb-toc-link targets, tracks the current heading, and controls the .imb-toc-drawer-root panel; it reads –imb-scroll-offset and uses the shared drawer events and body state. None of these files uses localized PHP settings beyond the settings and labels identified above.

• header.js: controls header and mobile bottom-bar visibility while scrolling.
• drawer.js: coordinates the mobile menu and sidebar drawers, shared overlay, ARIA state, and panel events.
• sidebar-sticky.js: calculates the CSS sticky top boundary for the desktop sidebar.
• page-top.js: scrolls the document or the currently open theme panel to its top.
• dropdown.js: manages desktop or tablet hover and focus dropdowns and mobile tap or height animation.
• scroll-animation.js: reveals .imb-animate elements once with IntersectionObserver.
• parallax.js: updates background-position through –imb-parallax-y for visible .imb-parallax elements.
• smooth-scroll.js: handles general same-page anchors with the shared fixed-header offset.
• table-of-contents.js: manages TOC fallback generation, details animation, scrolling, current heading state, and its drawer.

Theme Settings JavaScript

IM Base has one current admin script, assets/js/admin/theme-settings.js. It runs after the DOM loads and enables or disables conditional settings fields for desktop column widths, mobile drawer width, and post-list card or list options. It also opens the WordPress Media Library for configured image controls, updates or clears image previews and IDs, and copies displayed shortcodes using the Clipboard API with a fallback method when necessary.

PHP enqueues this script only on the IM Base theme settings screen and the Business Information, SNS Settings, and News Settings screens, identified by the hooks toplevel_page_imb-theme-settings, im-base_page_imb-business-information, im-base_page_imb-sns-settings, and im-base_page_imb-news-settings. The enqueue also loads the localized image-selection labels used by the Media Library control.

const imageControls = document.querySelectorAll('.imb-theme-settings__image-control');

if (imageControls.length && window.wp?.media) {
    // Open the WordPress media frame for each configured image control.
}

Script Loading and PHP Configuration

The standard front-end enqueue function iterates over the scripts listed in inc/enqueue.php. Each existing file under assets/js/ is registered with the imb- prefix, no dependencies, a version based on the file’s modification time, and footer loading enabled. Missing files are skipped. The theme also localizes header, responsive, and drawer settings to the relevant script handles.

The admin theme-settings script is enqueued only for the allowed admin hook suffixes: toplevel_page_imb-theme-settings, im-base_page_imb-business-information, im-base_page_imb-sns-settings, and im-base_page_imb-news-settings. Creator-defined front-end scripts use a separate enqueue function and the imb_custom_scripts filter; filtered file names are read from assets/js/, validated, and enqueued after the standard theme assets with custom handles, no dependencies, modification-time versions, and footer loading.

wp_enqueue_script(
    'imb-' . $script,
    get_theme_file_uri($relative_path),
    [],
    (string) filemtime($file_path),
    true
);

$scripts = apply_filters('imb_custom_scripts', $scripts);

DOM and Component Integration

Front-end modules depend on the established IM Base DOM contracts. Header templates output .imb-header, .imb-mobile-nav, .imb-header-nav, .imb-header-menu, .imb-header-item, .imb-header-item__dropdown, and .imb-header-menu__sub; the navigation walker assigns submenu IDs such as imb-global-submenu-{menu item ID}. Drawer controls use .imb-drawer-button, .imb-sidebar-open, .imb-sidebar, .imb-overlay, and .imb-body, with is_open, is_hidden, and is_drawer_open states. Preserve aria-expanded, aria-controls, aria-hidden, data-label-open, and data-label-close values when changing header, mobile navigation, sidebar, or page-top templates.

The TOC uses .imb-toc, .imb-toc-link, .imb-toc-details, .imb-toc-summary, .imb-toc-drawer-root, .imb-toc-drawer-toggle, .imb-toc-overlay, and .imb-toc-drawer, plus data-imb-toc-client and data-imb-toc-client-drawer placeholders with data-include-h3 and data-exclude-classes. Panel coordination uses the imb:panel-open, imb:close-drawers, and imb:toc-close custom events. Scroll anchors target heading IDs and use the –imb-scroll-offset custom property; animation and parallax hooks are .imb-animate with is-visible and .imb-parallax with –imb-parallax-y. The sidebar also uses –imb-sidebar-sticky-top.

These contracts are implemented by the related PHP templates and SCSS sources, including the header templates, mobile-nav.php, page-top.php, sidebar.php, inc/table-of-contents.php, layout header and sidebar files, and parts for drawers, overlays, page-top, animations, parallax, and TOC. Edit SCSS sources rather than generated CSS, and preserve the established class names and responsive states.

const drawerButton = document.querySelector('.imb-drawer-button');
const headerNav = document.querySelector('.imb-header-nav');
const sidebarButton = document.querySelector('.imb-sidebar-open');
const sidebar = document.querySelector('.imb-sidebar');
const overlay = document.querySelector('.imb-overlay');

const placeholder = document.querySelector('[data-imb-toc-client]');
const drawerPlaceholder = document.querySelector('[data-imb-toc-client-drawer]');

Responsive Settings and Coordinated Behavior

PHP localizes responsive breakpoints to the imb-header script as window.imbResponsiveSettings, including mobileMax, tabletMin, tabletMax, and desktopMin. It also passes desktop, mobile, and mobile bottom-bar scroll settings through window.imbHeaderSettings, with each value set to hide or always. The header uses tabletMin to distinguish Mobile behavior from Tablet and Desktop behavior, and keeps controls visible while a drawer is open or when the viewport range changes. The dropdown module uses mobileMax to select mobile interactions: mobile submenus use height animation, while tablet and desktop menus use hover and focus states; changing responsive ranges closes dropdowns and resets their inline styles.

Drawers coordinate through the shared overlay, the imb-body is_drawer_open state, and custom events including imb:panel-open, imb:close-drawers, and imb:toc-close. Opening one panel closes other drawers and notifies the header to keep its controls visible. Reduced-motion preferences disable or simplify motion across smooth scrolling, the Table of Contents details animation, scroll reveals, and parallax. CSS custom properties provide shared values such as –imb-scroll-offset for anchor and TOC scrolling, –imb-animation-duration and –imb-animation-distance for reveal effects, and –imb-parallax-y for parallax background positioning.

wp_localize_script(
    'imb-header',
    'imbResponsiveSettings',
    [
        'mobileMax'  => $breakpoints['mobile_max'],
        'tabletMin'  => $breakpoints['tablet_min'],
        'tabletMax'  => $breakpoints['tablet_max'],
        'desktopMin' => $breakpoints['desktop_min'],
    ]
);

const responsiveSettings = window.imbResponsiveSettings || {};
const mobileMax = Number.parseInt(responsiveSettings.mobileMax, 10);
const mobileViewport = window.matchMedia(`(max-width: ${mobileMax}px)`);

Adding JavaScript

Place the script in assets/js/. For a theme-standard module, add its file name to the scripts array in inc/enqueue.php. For creator-defined files, add the file name without its extension through the imb_custom_scripts filter; these files are loaded from assets/js/ after the theme assets.

Add only the imb-prefixed class, ID, or data attribute the script requires to the related template. If the interaction has visual states, update the related SCSS source and synchronize the generated CSS. Use wp_localize_script() when PHP values are needed in the browser, and read responsive breakpoints from window.imbResponsiveSettings rather than hardcoding them. Preserve existing ARIA attributes, keyboard and focus behavior, Escape handling, and reduced-motion behavior.

• Add the JavaScript file under assets/js/.
• Register a theme-standard module in the scripts array in inc/enqueue.php, or use the imb_custom_scripts filter for creator-defined files.
• Add the required imb- class, ID, or data attribute to the related template only when the script needs a DOM hook.
• Add or update the related SCSS Part or layout source when the interaction requires visual states.
• Use wp_localize_script() when PHP settings must be available to the browser; do not hardcode responsive breakpoints.