README

Yii Framework

jQuery

Optional jQuery integration layer for Yii2
Asset bundles, client-side validation scripts, and widget client scripts all jQuery-backed

Overview

This package restores the jQuery-powered client-side layer that was extracted from yii2-framework/yii2.

The package supports jQuery 3.7.1 and jQuery 4.0.0. The bundled npm dependency defaults to jQuery 3.7.1 so legacy Yii2 applications remain safe by default. Applications that want jQuery 4.0.0 must pin it explicitly in their project-level package.json.

Install it when your application still relies on classic Yii2 page flows such as:

yii.js data-method, confirmation, and CSRF helpers;
ActiveForm client-side and Ajax validation;
GridView filtering and checkbox selection scripts;
Captcha, MaskedInput, and Pjax jQuery integrations.

The package is intentionally optional. Applications that no longer need jQuery should avoid installing it and should provide an alternative client-side integration strategy instead.

Features

Quick start

Installation

composer require yii2-framework/jquery:^0.1

Asset installation

This package uses php-forge/foxy to install npm dependencies such as jQuery, Inputmask, and Punycode during composer install or composer update.

The @npm alias must point to your project's node_modules directory:

// config/web.php
return [
    'aliases' => [
        '@npm' => dirname(__DIR__) . '/node_modules',
    ],
    // ...
];

If npm packages are not installed automatically, verify that:

php-forge/foxy is allowed in your composer.json:

{
    "config": {
        "allow-plugins": {
            "php-forge/foxy": true
        }
    }
}

Run composer update to trigger the asset merge.

jQuery version selection

By default, this package installs jQuery 3.7.1.

If your application is ready to run on jQuery 4.0.0, pin it explicitly in the project-level package.json and run composer update again so the merged npm manifest is refreshed:

{
    "dependencies": {
        "jquery": "^4.0.0"
    }
}

Use the full jQuery build. This package depends on Ajax and Deferred APIs and is not compatible with the slim build.

Configuration

// config/web.php
return [
    'bootstrap' => [\yii\jquery\Bootstrap::class],
    // ...
];

Bootstrap configures the DI container with jQuery-based $clientScript defaults for validators and widgets that support strategy-based client integrations.

Overriding a single validator

public function rules(): array
{
    return [
        [
            'email',
            'required',
            'clientScript' => ['class' => MyCustomRequiredClientScript::class],
        ],
    ];
}

When to use this package

Use yii2-framework/jquery when your application still renders classic Yii2 views and depends on jQuery-backed widget behavior or client validation.

Do not use this package as the foundation for a new frontend modernization effort. When migrating away from jQuery, the recommended direction is to keep this package only on legacy pages and introduce a separate frontend integration layer for new pages.