Configuration

Letters is built on top of CKEditor 5 Framework. This gives you a lot of possibilities when it comes to customization. It should work with all CKEditor 5 configuration options for included plugins.

Additionally, Letters provides custom features, like the Finish editing or share button. You can find the documentation for their configuration in the Integration guide.

# Toolbar configuration

Letters contains two toolbars:

• Block toolbar – To change or insert a block
• Inline balloon toolbar – To change the style of the selected content or add a comment or link.

It is possible to adjust the toolbar configuration. However, note that the fact that you change the list of buttons in the toolbar does not change the list of loaded plugins. For instance, even if you remove the bold button from the toolbar, Letters will not remove support for the <strong> tag from your content. You will still be able to apply bold using the keyboard shortcut or autoformatting. To change the list of available plugins check the Plugin customization guide.

# Block toolbar

By default the block toolbar contains the following features:

blockToolbar: [
    'paragraph',
    'heading1',
    'heading2',
    'numberedList',
    'bulletedList',
    'blockQuote',
    'imageUpload'
]

In order to change it, provide the blockToolbar property to the Letters configuration object.

// app.js

import Letters from '@ckeditor/letters/src/letters';

Letters.create( document.querySelector( '#letters' ), {
    cloudServices: {
        // PROVIDE CORRECT VALUES HERE:
        tokenUrl: 'https://example.com/cs-token-endpoint',
        uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/',
        webSocketUrl: 'your-organization-id.cke-cs.com/ws/'
    },
    collaboration: {
        channelId: 'blockToolbar'
    },
    title: 'Welcome to Letters',
    body: '<p>Distraction-free writing and real-time collaborative editing made for you.</p>',
    blockToolbar: [
        'blockQuote',
        'paragraph',
        'heading1',
        'heading2'
    ]
} )
.then( letters => {
    window.letters = letters;
} )
.catch( error => console.error( error ) );

To learn more about the block toolbar see its guide.

# Balloon toolbar

By default the balloon toolbar contains the following features:

balloonToolbar: [
    'bold',
    'italic',
    'link',
    'comment'
],

In order to change it, provide the balloonToolbar property to the Letters configuration object.

// app.js

import Letters from '@ckeditor/letters/src/letters';

Letters.create( document.querySelector( '#letters' ), {
    cloudServices: {
        // PROVIDE CORRECT VALUES HERE:
        tokenUrl: 'https://example.com/cs-token-endpoint',
        uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/',
        webSocketUrl: 'your-organization-id.cke-cs.com/ws/'
    },
    collaboration: {
        channelId: 'balloonToolbar'
    },
    title: 'Welcome to Letters',
    body: '<p>Distraction-free writing and real-time collaborative editing made for you.</p>',
    balloonToolbar: [ 'link', 'comment' ],
} )
.then( letters => {
    window.letters = letters;
} )
.catch( error => console.error( error ) );

# Heading configuration

Letters uses CKEditor 5 HeadingButtonsUI to show the buttons to change heading levels (and ParagraphButtonUI to show the paragraph button).

By default Letters allows the user to use two heading levels. HeadingButtonsUI provides icons for three levels of headings, so you can easily add one more level of headings by changing the configuration:

// app.js

import Letters from '@ckeditor/letters/src/letters';

Letters.create( document.querySelector( '#letters' ), {
    heading: {
        options: [
            { model: 'paragraph', title: 'Paragraph' },
            { model: 'heading1', view: 'h2', title: 'Heading 1' },
            { model: 'heading2', view: 'h3', title: 'Heading 2' },
            { model: 'heading3', view: 'h4', title: 'Heading 3' }
        ]
    },
    blockToolbar: [
        'paragraph',
        'heading1',
        'heading2',
        'heading3',
        'numberedList',
        'bulletedList',
        'blockQuote',
        'imageUpload'
    ],
    cloudServices: {
        // PROVIDE CORRECT VALUES HERE:
        tokenUrl: 'https://example.com/cs-token-endpoint',
        uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/',
        webSocketUrl: 'your-organization-id.cke-cs.com/ws/'
    },
    collaboration: {
        channelId: 'headingConfiguration'
    },
    title: 'Welcome to Letters',
    body: '<p>Distraction-free writing and real-time collaborative editing made for you.</p>'
} )
.then( letters => {
    window.letters = letters;
} )
.catch( error => console.error( error ) );

Note that by default the <h4> element inside Letters will look just like regular text, so you need to introduce some style for it. To style content inside Letters, use the .ltrs-content class.

.ltrs-content h4 {
    font-weight: bold;
}

If you need more heading levels, custom icons need to be provided by using the icon property.