PHPackages                             rawilk/filament-quill - 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. [Templating & Views](/categories/templating)
4. /
5. rawilk/filament-quill

ActiveLibrary[Templating & Views](/categories/templating)

rawilk/filament-quill
=====================

Quill rich text editor for Filament.

v2.0.1(3d ago)3555.0k↓66.1%9MITPHPPHP ^8.3CI passing

Since Dec 20Pushed 6d ago2 watchersCompare

[ Source](https://github.com/rawilk/filament-quill)[ Packagist](https://packagist.org/packages/rawilk/filament-quill)[ Docs](https://github.com/rawilk/filament-quill)[ GitHub Sponsors](https://github.com/rawilk)[ RSS](/packages/rawilk-filament-quill/feed)WikiDiscussions main Synced today

READMEChangelog (6)Dependencies (21)Versions (18)Used By (0)

filament-quill
==============

[](#filament-quill)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7cede11ce69eb0f0dcc80f47609cac87d0a0a323bc1c738097d79d071fea10f2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f726177696c6b2f66696c616d656e742d7175696c6c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rawilk/filament-quill)[![Tests](https://github.com/rawilk/filament-quill/workflows/Tests/badge.svg?style=flat-square)](https://github.com/rawilk/filament-quill/workflows/Tests/badge.svg?style=flat-square)[![Total Downloads](https://camo.githubusercontent.com/87d981d0de86751f1b2164aca95c5bbe15104a8c6bfe8a781c681ef90a99b693/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f726177696c6b2f66696c616d656e742d7175696c6c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rawilk/filament-quill)[![PHP from Packagist](https://camo.githubusercontent.com/5cd9a4d847622423b1b540499e4fc592357b16f536d749b5ec3da9d2a06e063c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f726177696c6b2f66696c616d656e742d7175696c6c3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rawilk/filament-quill)[![License](https://camo.githubusercontent.com/b866b6984ac0428e1005cc04faa6c4d2798e38d02db1331de78a3f2517f77a5f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f726177696c6b2f66696c616d656e742d7175696c6c3f7374796c653d666c61742d737175617265)](https://github.com/rawilk/filament-quill/blob/main/LICENSE.md)

[![social image](https://github.com/rawilk/filament-quill/raw/main/art/social-image.png?raw=true)](https://github.com/rawilk/filament-quill/blob/main/art/social-image.png?raw=true)

`filament-quill` offers a [Quill](https://quilljs.com) rich text editor integration for filament admin panels and forms.

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

[](#requirements)

- PHP 8.3 or higher
- Laravel 12 or higher
- Filament 5 (should work with Filament 4 too)

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

[](#installation)

You can install the package via composer:

```
composer require rawilk/filament-quill
```

You can publish the config file with:

```
php artisan vendor:publish --tag="filament-quill-config"
```

You can view the default configuration here:

If you need to, you can publish the views and translations with:

```
php artisan vendor:publish --tag="filament-quill-views"
php artisan vendor:publish --tag="filament-quill-translations"
```

For more information on setup necessary to render editor content, see the [Rendering Content](#rendering-content) section.

Upgrading
---------

[](#upgrading)

Upgrading from a v1.x? See the [upgrade guide](UPGRADE.md).

Usage
-----

[](#usage)

The editor has been set up to behave like and have a similar api to the rich text editor component provided by Filament. One major difference between Filament's editor and the package's editor is Filament is using Tiptap for the editor, while this package is using Quill.

Here's a quick example of how to use the editor in a filament form:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content'),
```

This will provide an editor that will look like this in your form:

[![basic example](https://github.com/rawilk/filament-quill/raw/main/art/basic.png?raw=true)](https://github.com/rawilk/filament-quill/blob/main/art/basic.png?raw=true)

Toolbar Buttons
---------------

[](#toolbar-buttons)

The editor ships with a default toolbar. Please consult the `ToolbarButton` enum for a full list of available toolbar buttons. These are the defaults:

```
use Rawilk\FilamentQuill\Enums\ToolbarButton;

[
    ToolbarButton::Font,
    ToolbarButton::Size,
    ToolbarButton::Bold,
    ToolbarButton::Italic,
    ToolbarButton::Underline,
    ToolbarButton::Strike,
    ToolbarButton::BlockQuote,
    ToolbarButton::OrderedList,
    ToolbarButton::UnorderedList,
    ToolbarButton::Indent,
    ToolbarButton::Link,
    ToolbarButton::Image,
    ToolbarButton::Scripts,
    ToolbarButton::TextAlign,
    ToolbarButton::TextColor,
    ToolbarButton::BackgroundColor,
    ToolbarButton::Undo,
    ToolbarButton::Redo,
    ToolbarButton::ClearFormat,
    ToolbarButton::Header,
]
```

You may alternatively use the `disableToolbarButtons()` method to disable specific buttons:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;
use Rawilk\FilamentQuill\Enums\ToolbarButton;

QuillEditor::make('content')
    ->disableToolbarButtons([
        ToolbarButton::BlockQuote,
        ToolbarButton::Font,
    ])
```

You can also enable specific toolbar buttons using the `enableToolbarButtons()` method:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;
use Rawilk\FilamentQuill\Enums\ToolbarButton;

QuillEditor::make('content')
    ->enableToolbarButtons([
        ToolbarButton::CodeBlock,
    ])
```

Placeholders
------------

[](#placeholders)

A requirement I often have for rich text editors is the ability to provide a list of placeholder variables that an end-user can select and insert into the editor. My most common use case for this is for email templates. I've made it simple to do this in this package. All you need to do is provide an array of placeholders to the component.

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content')
    ->placeholders([
        'USER_NAME',
        'USER_EMAIL',
        'CURRENT_DATE',
    ])
```

[![placeholders example](https://github.com/rawilk/filament-quill/raw/main/art/placeholders.png?raw=true)](https://github.com/rawilk/filament-quill/blob/main/art/placeholders.png?raw=true)

As you can see, we take care of adding the toolbar button and registering a [Handler](#handlers) to insert the placeholder variable into the editor for you. The editor will surround the variable with the `[` and `]` characters before the variable is inserted, however these characters can be [customized](#surrounding-characters).

**Note:** Parsing and replacing your variables in your content is outside the scope of this form component. You will need to handle that part yourself.

### Surrounding Characters

[](#surrounding-characters)

By default, we will surround a variable with `[` and `]` before it's inserted into the editor, so a the `USER_NAME` variable would become `[USER_NAME]` when we insert it.

To change these characters, you can use the `surroundPlaceholdersWith()` method:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content')
    ->placeholders([
        'USER_NAME',
        'USER_EMAIL',
        'CURRENT_DATE',
    ])
    ->surroundPlaceholdersWith(start: '{{ ', end: ' }}')
```

Now when a variable is inserted, it will look like `{{ USER_NAME }}` instead.

### Placeholder Button Label

[](#placeholder-button-label)

To change the text on the placeholder button, you can either modify the `filament-quill::quill.placeholders.label` translation, or you can pass in a label via the `placeholderButtonLabel()` method.

Handlers
--------

[](#handlers)

If you want to override a handler for an existing toolbar button, you can define your custom JavaScript [handlers](https://quilljs.com/docs/modules/toolbar/#handlers) using the `handlers()` method. Here's an example of how to use your own handler for the `bold` toolbar button:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content')
    ->handlers([
        'bold' => fileAttachmentsDisk('s3')
    ->fileAttachmentsDirectory('attachments')
    ->fileAttachmentsVisibility('private')
```

Note: We do not handle tracking and managing the uploaded images. For example, if an image is deleted from the content, we will not remove it from the server, so images have a high probability of becoming orphaned. We will dispatch a `quill-image-uploaded` alpine event when we upload an image, and a `quill-images-deleted` alpine event when our JavaScript detects an image has been removed from the content. Both of these events will receive the fully qualified urls of the relevant images, and the name of the field the event was dispatched from. You could listen for these events and track the absolute urls of the images:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content')
    ->extraAlpineAttributes([
        '@quill-image-uploaded' =>  allowImageResizing()
```

You may also enable it globally for every editor by setting `allow_image_resizing` to `true` in the published `config/filament-quill.php` file. The per-editor method always takes precedence over the config value, so you can opt a single editor out again with `->allowImageResizing(false)`.

Resized dimensions are saved as `width` and `height` attributes on the `` tag, and alignment is saved as a `data-align` attribute — no inline styles are added, so the stored HTML stays clean and the values are preserved when the content is loaded back into the editor. The alignment is rendered from the package's `content.css` styles, so make sure those styles are loaded both in the editor and wherever you [render the content](#rendering-content).

Rendering Content
-----------------

[](#rendering-content)

To match the formatting you will see in the editor, wrap your user-generated content inside a container with the `quill-content prose max-w-none` classes on it. You will also need to load the package's content styles wherever you render saved editor HTML. We've extracted those styles into a separate stylesheet, called `content.css`. If you haven't set up a custom theme and are using a panel, follow the [Filament docs](https://filamentphp.com/docs/5.x/styling/overview) first.

The following will apply in both a panel and standalone as well.

1. In your Tailwind CSS 4 theme stylesheet, register the package views as a source and import the content styles:

```
@import "tailwindcss";

@source "/rawilk/filament-quill/resources/**/*.blade.php";
@source inline("quill-content prose max-w-none dark:prose-invert");

@import "/rawilk/filament-quill/resources/css/content.css";
```

If your theme stylesheet already imports Tailwind, add the package `@source` rules and `content.css` import to that same file instead of creating a second Tailwind entrypoint.

2. If you use the `prose` classes shown below, make sure your theme includes Tailwind's typography plugin:

```
@plugin "@tailwindcss/typography";
```

3. If you need to load all package styles manually, you can import `app.css` instead. This is usually not recommended for normal Filament fields because the package loads the editor styles for you.

```
@import "/rawilk/filament-quill/resources/css/app.css";
```

4. If your app is still migrating to Tailwind CSS 4, make sure your PostCSS setup uses the Tailwind 4 plugin:

```
module.exports = {
    plugins: {
        "postcss-import": {},
        "@tailwindcss/postcss": {},
        autoprefixer: {},
    },
};
```

5. Rebuild your custom theme.

```
npm run build
```

6. Render the content

```
@use(Illuminate\Support\HtmlString)

    {{ new HtmlString($yourContent) }}

```

You can also add `dark:prose-invert` to your container if you're supporting dark mode for the content rendering.

It's also generally a good idea to run your content through a html purifier, however that is outside the scope of these docs.

### Custom Fonts

[](#custom-fonts)

If you have the `ToolbarButton::Font` button enabled, we will render a dropdown allowing the user to format their content with `Sans Serif`, `Serif`, or `Monospaced` font families. You will need to pull in and register those font families manually, however. In a panel, you could take advantage of the `panels::head.start` [Render Hook](https://filamentphp.com/docs/5.x/advanced/render-hooks) to accomplish this.

In the code below, we're going to pull in `Fira Code` and `PT Serif` monospace and serif fonts to use, however the process is similar to custom fonts as well.

```

    :root {
        --font-serif-family: "PT Serif";
        --font-mono-family: "Fira Code";
    }

```

#### Registering the font families

[](#registering-the-font-families)

In the package's stylesheet, we configure monospace and serif font families to look for the `--font-serif-family` and `--font-mono-family` css variables in the editor area. When rendering your own content independently, you can register those fonts in your theme stylesheet with Tailwind's CSS configuration syntax.

```
@theme {
    --font-quill-serif:
        var(--font-serif-family), ui-serif, Georgia, Cambria, "Times New Roman",
        Times, serif;
    --font-quill-mono:
        var(--font-mono-family), ui-monospace, SFMono-Regular, Menlo, Monaco,
        Consolas, "Liberation Mono", "Courier New", monospace;
}
```

#### Using custom font families

[](#using-custom-font-families)

If you want to use custom font families, like "Times New Roman", or something like that, you can use the `useFonts()` method on the component:

> Be sure to follow the [Rendering Content](#rendering-content) section first to make sure you have everything setup for this.

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content')
    ->useFonts([
        'Times New Roman',
    ])
```

Based on the [registering the font families](#registering-the-font-families) section, you will need to register the font in your stylesheet. We will map each font family value to a slug, so the "Times New Roman" font above will be mapped to "times-new-roman".

```
@theme {
    --font-quill-times: "Times New Roman", Times, serif;
}
```

In a custom stylesheet, you will need to target the areas of the content that are formatted with this font:

```
.quill-content {
    &,
    .ql-editor {
        .ql-times-new-roman,
        .ql-editor .ql-times-new-roman {
            @apply font-quill-times;
        }
    }
}
```

Be sure to replace `.ql-times-new-roman` and `font-quill-times` with your actual font names.

### Custom font sizes

[](#custom-font-sizes)

When the `ToolbarButton::Size` button is enabled, we will show a dropdown of font sizes the user can use to format their content with. Like with the [font families](#custom-fonts), you are free to define your own sizes. You can pass an array of font sizes to the `fontSizes` method:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content')
    ->fontSizes([
        '10px',
        '12px',
        '14px',
        '20px',
    ])
```

When you provide actual CSS size units, Quill will inline the text size right on the content, so no additional styling will be required. However, if you provide non-standard sizes, like "Small" or "Large", you will need to target those selectors in your css. The selectors follow a scheme of: `ql-size-{size}`.

```
.ql-size-small,
.ql-editor .ql-size-small {
    font-size: 0.75rem;
}
```

### Custom colors

[](#custom-colors)

When you have the `ToolbarButton::TextColor` and `ToolbarButton::BackgroundColor` buttons enabled, you are free to specify your own color pallet using css hex color codes.

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

$colors = [
    '#fff',
    '#ff0000',
    '#333',
    // ...
];

QuillEditor::make('content')
    ->textColors($colors)
    ->backgroundColors($colors)
```

History
-------

[](#history)

By default, the editor includes toolbar buttons for undo/redo history actions. When dealing with [Images](#uploading-images) or some other use-cases, you may want to reset the history state of the editor so the user can't "undo" a change back to a broken image if you removed it from the server. This can easily be accomplished by calling the `clearHistory` method on the component from an action, for example.

Here's an example of resetting the history state on an edit resource page form using the `afterSave` hook:

```
use Filament\Forms\Components\Component;

protected function afterSave(): void
{
    $component = $this->form->getComponent('data.content');

    $component->clearHistory();
}
```

Behind the scenes, the editor component will dispatch the `quill-history-clear` browser event, which our javascript will be listening for. If you aren't able to get a component instance, you can manually dispatch the event yourself. You will just need to know the state path for the component (typically `data.your_field_name`).

```
$this->dispatch('quill-history-clear', id: 'data.content');
```

Other Callbacks
---------------

[](#other-callbacks)

### onInit

[](#oninit)

Using the `onInit` callback, you are able to register additional handlers or callbacks on the quill editor instance, and more. This can be a great place to register your own [Event](https://quilljs.com/docs/api/#events) handlers on the editor instance. All you need to do is provide a JavaScript callback to the `onInit()` method:

```
use Rawilk\FilamentQuill\Filament\Forms\Components\QuillEditor;

QuillEditor::make('content')
    ->onInit(onTextChange(