README

Leer en español

An independent, installable Bootstrap 5 theme for KCFinder Resurrected. KCFinder Resurrected continues the archived sunhater/kcfinder project originally created by Pavel Tzonkov.

This repository is a community project. It is not an official Bootstrap project and it does not replace or modify the KCFinder core.

Highlights

Bootstrap 5 visual language without loading Bootstrap from a CDN.
Local Bootstrap Icons for toolbars, folders, menus, dialogs and form controls.
Responsive folder panel for narrow screens.
Styled optional folder and file name search provided by compatible KCFinder versions.
Refined thumbnail and list views.
Consistent radio buttons, checkboxes and language selector while preserving KCFinder's existing transForm behavior.
Self-contained production package: PHP, Node.js and Composer dependencies are not added to KCFinder.

Compatibility

KCFinder Resurrected 4.x; the optional name search requires 4.7 or newer.
Bootstrap 5.3.8 design tokens and Bootstrap Icons 1.13.1.
Current versions of Chrome, Edge and Firefox. Safari should work but is not yet part of the regular test pass.

The theme does not change KCFinder's PHP requirements, authentication, uploads, permissions or security configuration.

On current KCFinder Resurrected versions, the theme reuses the folder drawer and focus management provided by the core. A compatible fallback remains available for earlier 4.x installations, so a visual theme update does not force a server-side upgrade first.

When the optional KCFinder name search is enabled in conf/config.local.php, the theme automatically styles its field, progress text, matches and result counts. Search execution and limits remain core configuration; the theme does not scan files itself.

Install

1. Obtain the theme

Download a release, or clone this repository and use the already-built dist/bootstrap5 directory.

Composer is also supported:

composer require krma-cl/kcfinder-bootstrap5-theme:^0.3

Copy vendor/krma-cl/kcfinder-bootstrap5-theme/dist/bootstrap5 into the KCFinder themes directory. The Laravel adapter's asset command can automate the application-side publication workflow.

For standalone Composer installations, publish it without editing either package under vendor:

vendor/bin/kcfinder-theme-install --target=/path/to/public/kcfinder/themes

Use --force for an intentional update. Publication is staged and then replaced atomically.

2. Copy the production directory

Copy the complete directory:

dist/bootstrap5

into the themes directory of your KCFinder installation. The resulting layout must be:

kcfinder/
└── themes/
    └── bootstrap5/
        ├── 01.ui.css
        ├── 02.transForm.css
        ├── 03.bootstrap.css
        ├── css.php
        ├── init.js
        ├── js.php
        └── img/

Do not copy src, scripts, node_modules or vendor to the production server.

3. Select the theme

Set the default in conf/config.php:

'theme' => 'bootstrap5',

An integration may select it through the session instead:

$_SESSION['KCFINDER']['theme'] = 'bootstrap5';

The KCFinder jQuery adapter also accepts the theme option:

$('#file-browser').kcfinder({
    url: '/kcfinder/browse.php',
    theme: 'bootstrap5'
});

For a temporary test, open:

/kcfinder/browse.php?theme=bootstrap5

The URL option should be treated as a preview mechanism. Prefer configuration or session selection in production.

4. Clear generated theme caches

After installing or updating, remove these generated files if they exist:

cache/theme_bootstrap5.css
cache/theme_bootstrap5.js

KCFinder recreates them automatically. A hard browser refresh may also be required after an update.

Update

Back up themes/bootstrap5 if it contains local changes.
Replace it with the new dist/bootstrap5 directory.
Remove the two generated cache files listed above.
Reload KCFinder and test thumbnail view, list view, upload and dialogs.

Avoid editing files inside dist/bootstrap5 directly. Make source changes in src and rebuild so updates remain reproducible.

Uninstall

Change the configured theme back to default, remove themes/bootstrap5, and delete any generated theme_bootstrap5 cache files.

Development

Development requires Node.js 20 or newer and npm:

npm ci
npm run build
npm run check

Source files live in src. The build combines them with compatibility assets under vendor/kcfinder and writes the installable package to dist/bootstrap5.

Before committing, run:

npm run check
git diff --exit-code -- dist/bootstrap5

The second command confirms that the committed distribution matches the source. See CONTRIBUTING.md for the contribution workflow.

Versioning

The theme follows Semantic Versioning independently from KCFinder. Bootstrap and Bootstrap Icons versions are pinned in package.json and recorded in the changelog. Every distribution includes VERSION plus manifest.json, with the theme, Bootstrap and Bootstrap Icons versions and SHA-256 hashes for installed files.

Project lineage and credits

KCFinder Resurrected, maintained by krma-cl.
KCFinder, originally created by Pavel Tzonkov and now archived.
Bootstrap and Bootstrap Icons, maintained by the Bootstrap team.

Maintenance and community

This official KCFinder theme is maintained by KRMA together with its community of users and contributors. KRMA provides development, coordination and infrastructure to support the project's continuity.

License

The theme is available under GPL-3.0-or-later OR LGPL-3.0-or-later, matching KCFinder's license choice. Bootstrap and Bootstrap Icons are distributed under the MIT License. See LICENSE, the full texts under licenses, and THIRD_PARTY_NOTICES.md.

krma-cl / kcfinder-bootstrap5-theme

Maintainers

Package info

Statistics

Security