PHPackages                             promethys/checkbox-tree - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. promethys/checkbox-tree

ActiveLibrary[Utility & Helpers](/categories/utility)

promethys/checkbox-tree
=======================

A Filament form component that provides hierarchical checkbox selection with parent-child relationships.

1.0.0(3mo ago)24↓50%1[1 issues](https://github.com/Promethys/checkbox-tree/issues)MITPHPPHP ^8.1CI passing

Since Feb 1Pushed 3mo agoCompare

[ Source](https://github.com/Promethys/checkbox-tree)[ Packagist](https://packagist.org/packages/promethys/checkbox-tree)[ Docs](https://github.com/promethys/checkbox-tree)[ GitHub Sponsors](https://github.com/promethys)[ RSS](/packages/promethys-checkbox-tree/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (11)Versions (3)Used By (0)

Filament Checkbox Tree
======================

[](#filament-checkbox-tree)

[![Latest Version on Packagist](https://camo.githubusercontent.com/f74294dc09f3d27156b6ac78eb5cf50720fa5a60d65983a4429971b75e019933/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70726f6d65746879732f636865636b626f782d747265652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/promethys/checkbox-tree)[![GitHub Tests Action Status](https://camo.githubusercontent.com/f09c6e7e751172723b389973f5f180f5f94a0d4fd7f6a630692d602d9c9d421a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70726f6d65746879732f636865636b626f782d747265652f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/Promethys/checkbox-tree/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/b6f658d4e375a34943f5d3aee975b673e66be46637775feff8aa4bf55e8ca0a0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f70726f6d65746879732f636865636b626f782d747265652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/promethys/checkbox-tree)

If this plugin is useful to you, consider [giving it a ⭐ on GitHub](https://github.com/Promethys/checkbox-tree).

This plugin provides a hierarchical checkbox tree component for Filament forms. Display checkboxes in a parent-child tree structure with automatic state management.

Architecture & Compatibility
--------------------------------

[](#architecture--compatibility)

This component extends [Filament's native CheckboxList component](https://filamentphp.com/docs/3.x/forms/fields/checkbox-list), ensuring seamless integration with the Filament ecosystem while adding powerful hierarchical capabilities:

**Preserved CheckboxList Features:**

- All validation methods (`required()`, `rules()`, etc.)
- Bulk actions (`bulkToggleable()`, `selectAllAction()`, `deselectAllAction()`)
- Search functionality (`searchable()`, `searchPrompt()`)
- Disabled state (`disabled()`)
- Relationship handling (`relationship()`)
- State management methods (`default()`, `dehydrateStateUsing()`)
- HTML support (`allowHtml()`)
- Splitting options into columns (`columns()`, `gridDirection()`)
- Full compatibility with Filament's styling system and dark mode

**Enhanced for Hierarchical Use:**

- **Descriptions**: Integrated directly into the options array structure for better organization
- **State Management**: Intelligent parent-child state synchronization with indeterminate states
- **Data Storage**: Configurable leaf-only or full hierarchy storage
- **Tree Operations**: Collapsible sections and parent-child selection logic

This architecture ensures you get all the familiar CheckboxList functionality plus powerful new features specifically designed for hierarchical data structures.

Features
--------

[](#features)

- **Hierarchical Structure** - Display checkboxes in unlimited nested levels
- **Parent-Child Control** - Checking a parent automatically selects all children
- **Indeterminate States** - Visual indication when only some children are selected
- **Collapsible Sections** - Expand/collapse parent nodes with smooth animations
- **Search** - Filter tree items by keyword, shows parents when children match
- **Bulk Actions** - Select all / Deselect all buttons with customizable labels
- **Native Filament Styling** - Uses Filament's checkbox component, works with custom themes
- **Dark Mode Support** - Fully compatible with Filament's dark mode
- **Flat Array Storage** - Stores selections as a simple array, compatible with JSON columns and relationships

How It Works
------------

[](#how-it-works)

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/how-it-works.gif)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/how-it-works.gif)

 1. **Check a parent** - All children become checked, parent shows as checked
2. **Uncheck a parent** - All children become unchecked
3. **Check some children** - Parent shows indeterminate state (dash)
4. **Check all children** - Parent automatically becomes checked
5. **Uncheck all children** - Parent automatically becomes unchecked

Use Cases
---------

[](#use-cases)

- Permission management with grouped permissions
- Category/subcategory selection
- Feature flags with hierarchical options
- Department/team hierarchies
- Any multi-level checkbox selection

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10.x+
- Filament 3.x

Installation
------------

[](#installation)

Install via Composer:

```
composer require promethys/checkbox-tree
```

Publish Filament assets (required):

```
php artisan filament:assets
```

Clear caches:

```
php artisan optimize:clear
```

Usage
-----

[](#usage)

```
use Promethys\CheckboxTree\CheckboxTree;

CheckboxTree::make('permissions')
    ->label('Permissions')
    ->options([
        'user_management' => [
            'label' => 'User Management',
            'children' => [
                'create_users' => 'Create Users',
                'edit_users' => 'Edit Users',
                'delete_users' => 'Delete Users',
            ],
        ],
        'content_management' => [
            'label' => 'Content Management',
            'children' => [
                'create_posts' => 'Create Posts',
                'edit_posts' => 'Edit Posts',
                'publish_posts' => 'Publish Posts',
            ],
        ],
    ])
```

### Stored Data Format

[](#stored-data-format)

By default, only leaf nodes (items without children) are stored:

```
['create_users', 'edit_users', 'delete_users']
```

This works seamlessly with:

- JSON database columns
- Pivot tables via Filament relationships
- Simple array storage

To include parent keys in the stored value, use `storeParentKeys()`:

```
CheckboxTree::make('permissions')
    ->storeParentKeys()
    ->options([...])

// Stored value: ['user_management', 'create_users', 'edit_users', 'delete_users']
```

### Flat Options with parent\_id

[](#flat-options-with-parent_id)

You can provide flat options with `parent_id` references instead of manually nesting:

```
CheckboxTree::make('permissions')
    ->hierarchical('parent_id')
    ->options([
        'user_management' => ['label' => 'User Management', 'parent_id' => null],
        'create_users' => ['label' => 'Create Users', 'parent_id' => 'user_management'],
        'edit_users' => ['label' => 'Edit Users', 'parent_id' => 'user_management'],
        'delete_users' => ['label' => 'Delete Users', 'parent_id' => 'user_management'],
        'post_management' => ['label' => 'Post Management', 'parent_id' => null],
        'create_posts' => ['label' => 'Create Posts', 'parent_id' => 'post_management'],
    ])
```

The component automatically builds the tree structure. Items with `parent_id => null` become root items.

The label field must be `label`. Falls back to the array key if `label` is not provided.

### Descriptions

[](#descriptions)

Add description text below checkbox labels:

```
CheckboxTree::make('permissions')
    ->options([
        'admin' => [
            'label' => 'Administrator',
            'description' => 'Full system access',
            'children' => [
                'manage_users' => [
                    'label' => 'Manage Users',
                    'description' => 'Create, edit, and delete users',
                ],
                'manage_settings' => 'Manage Settings',
            ],
        ],
    ])
```

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/descriptions-1.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/descriptions-1.png)

Descriptions are optional and displayed in smaller, muted text below the label.

### HTML Support

[](#html-support)

By default, Filament escapes any HTML in option labels (native behavior inherited from CheckboxList). If you'd like to allow HTML, you can use the `allowHtml()` method. The plugin supports HTML formatting for both labels and descriptions:

```
CheckboxTree::make('permissions')
    ->options([
        'admin' => [
            'label' => 'Administrator',
            'description' => 'Full system access',
            'children' => [
                'manage_users' => [
                    'label' => 'Manage Users',
                    'description' => 'Create, edit, and delete users',
                ],
                'manage_settings' => 'Manage Settings',
            ],
        ],
    ])
    ->allowHtml()
```

You can also use instances of `Illuminate\Support\HtmlString` or `Illuminate\Contracts\Support\Htmlable`. This approach provides better security and allows you to render HTML or even markdown:

```
CheckboxTree::make('permissions')
    ->options([
        'admin' => [
            'label' => new HtmlString('Administrator'),
            'description' => str('**Full system** access')->inlineMarkdown()->toHtmlString(),
            'children' => [
                'manage_users' => [
                    'label' => new HtmlString('Manage Users'),
                    'description' => str('**Create**, **edit**, and **delete** users')->inlineMarkdown()->toHtmlString(),
                ],
                'manage_settings' => new HtmlString('Manage Settings'),
            ],
        ],
    ])
```

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/descriptions-2.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/descriptions-2.png)

> **Security Warning**: Always ensure that HTML content is safe to render. User-generated content should be properly sanitized to prevent XSS attacks.

### Multi-Level Nesting

[](#multi-level-nesting)

The component supports unlimited nesting depth:

```
CheckboxTree::make('categories')
    ->options([
        'electronics' => [
            'label' => 'Electronics',
            'children' => [
                'computers' => [
                    'label' => 'Computers',
                    'children' => [
                        'laptops' => 'Laptops',
                        'desktops' => 'Desktops',
                    ],
                ],
                'phones' => 'Mobile Phones',
            ],
        ],
    ])
```

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/multi-level.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/multi-level.png)

### With Validation

[](#with-validation)

Standard Filament validation works:

```
CheckboxTree::make('permissions')
    ->required()
    ->options([...])
```

### Disabled State

[](#disabled-state)

```
CheckboxTree::make('permissions')
    ->disabled()
    ->options([...])
```

### Disabling Specific Options

[](#disabling-specific-options)

Disable individual options using a closure:

```
CheckboxTree::make('permissions')
    ->disableOptionWhen(fn (string $value): bool => $value === 'delete_users')
    ->options([...])
```

When a parent is disabled, all its children are automatically disabled too:

```
// Disables "User Management" and all its children
CheckboxTree::make('permissions')
    ->disableOptionWhen(fn (string $value): bool => $value === 'user_management')
    ->options([...])
```

When all children of a parent are disabled, the parent is automatically disabled as well:

```
// Disables all children of "User Management", so the parent becomes disabled too
CheckboxTree::make('permissions')
    ->disableOptionWhen(fn (string $value): bool => in_array($value, [
        'create_users', 'edit_users', 'delete_users',
    ]))
    ->options([...])
```

### Collapsible Sections

[](#collapsible-sections)

Enable collapsible parent nodes:

```
CheckboxTree::make('permissions')
    ->collapsible()
    ->options([...])
```

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/collapsible-1.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/collapsible-1.png)

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/collapsible-2.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/collapsible-2.png)

Start with all sections collapsed:

```
CheckboxTree::make('permissions')
    ->collapsible(defaultCollapsed: true)
    ->options([...])
```

### Search

[](#search)

Enable search to filter tree items:

```
CheckboxTree::make('permissions')
    ->searchable()
    ->options([...])
```

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/searchable.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/searchable.png)

Customize the search placeholder:

```
CheckboxTree::make('permissions')
    ->searchable()
    ->searchPrompt('Search permissions...')
    ->options([...])
```

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/searchable-custom-placeholder.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/searchable-custom-placeholder.png)

When searching, parent nodes are shown if any of their children match the search term.

### Bulk Actions

[](#bulk-actions)

Enable "Select all / Deselect all" buttons:

```
CheckboxTree::make('permissions')
    ->bulkToggleable()
    ->options([...])
```

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/bulk-toggleable.png)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/bulk-toggleable.png)

Customize the action labels:

```
CheckboxTree::make('technologies')
    ->bulkToggleable()
    ->selectAllAction(
        fn ($action) => $action->label('Select all technologies')
    )
    ->deselectAllAction(
        fn ($action) => $action->label('Clear selection')
    )
    ->options([...])
```

### Eloquent Relationships

[](#eloquent-relationships)

Build a tree directly from a `BelongsToMany` relationship with hierarchical records:

```
// Model: Permission has parent_id column
CheckboxTree::make('permissions')
    ->relationship('permissions', 'name')
    ->hierarchical('parent_id')
```

The component will:

1. Fetch all related records from the pivot table
2. Build a tree structure based on `parent_id`
3. Save selected values back to the pivot table

With query modification:

```
CheckboxTree::make('permissions')
    ->relationship(
        'permissions',
        'name',
        fn ($query) => $query->where('active', true)
    )
    ->hierarchical('parent_id')
```

Known Issues
------------

[](#known-issues)

**Checkbox flickering in multi-column layouts** — When using `columns()` with collapsible or searchable trees, checkboxes may occasionally flicker or briefly disappear during column reflow (collapse/expand, search filtering). This is a browser rendering bug with CSS multi-column layouts and dynamic content. The checkboxes remain functional — only the visual rendering is affected. Reloading the page or triggering a repaint (e.g. resizing the window) resolves it.

[![](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/known-issue-1.gif)](https://raw.githubusercontent.com/Promethys/checkbox-tree/refs/heads/main/resources/assets/imgs/known-issue-1.gif)

 Development
-----------

[](#development)

```
# Clone the repository
git clone https://github.com/promethys/checkbox-tree.git

# Install dependencies
composer install
npm install

# Build assets
npm run build

# Run tests
composer test
```

Changelog
---------

[](#changelog)

See [CHANGELOG](CHANGELOG.md) for recent changes.

Issue Guidelines
----------------

[](#issue-guidelines)

If you encounter a bug or unexpected behavior, please help us help you by following these guidelines:

- **[Create an issue on GitHub](https://github.com/Promethys/checkbox-tree/issues)**: Create an issue on GitHub
- **Describe the issue clearly:** What did you try to do? What did you expect to happen? What actually happened?
- **Include relevant code snippets:** Show any relevant model, config, or page setup related to the issue.
- **Share error messages:** If possible, paste the full error output or stack trace.
- **Attach screenshots:** Visuals often help us understand UI-related bugs or logic problems more quickly.
- **Mention your setup:** Let us know your PHP version, Laravel version, Filament version, and the version of this plugin.

> The more details you provide, the faster and better we can help. Thank you!

Contributing
------------

[](#contributing)

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Run `composer format` to apply code style (Laravel Pint)
3. Add tests for any new functionality (`composer test`)
4. Ensure PHPStan passes (`composer analyse`)
5. Submit a pull request with a clear description

License
-------

[](#license)

The MIT License (MIT). See [LICENSE](LICENSE.md) for more information.

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance70

Regular maintenance activity

Popularity9

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 95.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

106d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d0c12cfb51621902748a21257ff75234b28d84130fd6932312ddad893945656e?d=identicon)[nirine1](/maintainers/nirine1)

---

Top Contributors

[![nirine1](https://avatars.githubusercontent.com/u/106626867?v=4)](https://github.com/nirine1 "nirine1 (47 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

---

Tags

laravelPromethyscheckbox-tree

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/promethys-checkbox-tree/health.svg)

```
[![Health](https://phpackages.com/badges/promethys-checkbox-tree/health.svg)](https://phpackages.com/packages/promethys-checkbox-tree)
```

###  Alternatives

[codewithdennis/filament-select-tree

The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths.

320392.1k17](/packages/codewithdennis-filament-select-tree)[ralphjsmit/laravel-filament-components

A collection of reusable components for Filament.

10972.2k2](/packages/ralphjsmit-laravel-filament-components)[schmeits/filament-character-counter

This is a Filament character counter TextField and Textarea form field for Filament v4 and v5

33184.7k6](/packages/schmeits-filament-character-counter)[defstudio/filament-searchable-input

A searchable autocomplete input for Filament forms

3212.4k](/packages/defstudio-filament-searchable-input)[codebar-ag/laravel-filament-json-field

A Laravel Filament JSON Field integration with CodeMirror support

1124.1k](/packages/codebar-ag-laravel-filament-json-field)[ralphjsmit/laravel-helpers

A package containing handy helpers for your Laravel-application.

13704.6k2](/packages/ralphjsmit-laravel-helpers)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)