@ckeditor/ckeditor5-font

/** * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options */ /** * @module font/fontconfig */ import type { ColorOption, ColorPickerConfig } from "@ckeditor/ckeditor5-ui"; import type { MatcherPattern, ViewElementDefinition } from "@ckeditor/ckeditor5-engine"; /** * The configuration of the font color and font background color features. * This option is used by the {@link module:font/fontcolor/fontcolorediting~FontColorEditing} and * {@link module:font/fontbackgroundcolor/fontbackgroundcolorediting~FontBackgroundColorEditing} features. * * ```ts * ClassicEditor * .create( { * fontColor: ... // Font color feature configuration. * fontBackgroundColor: ... // Font background color feature configuration. * } ) * .then( ... ) * .catch( ... ); * ``` * * See {@link module:core/editor/editorconfig~EditorConfig all editor options}. */ export interface FontColorConfig { /** * Available font colors defined as an array of strings or objects. * * The default value registers the following colors: * * ```ts * const fontColorConfig = { * colors: [ * { * color: 'hsl(0, 0%, 0%)', * label: 'Black' * }, * { * color: 'hsl(0, 0%, 30%)', * label: 'Dim grey' * }, * { * color: 'hsl(0, 0%, 60%)', * label: 'Grey' * }, * { * color: 'hsl(0, 0%, 90%)', * label: 'Light grey' * }, * { * color: 'hsl(0, 0%, 100%)', * label: 'White', * hasBorder: true * }, * { * color: 'hsl(0, 75%, 60%)', * label: 'Red' * }, * { * color: 'hsl(30, 75%, 60%)', * label: 'Orange' * }, * { * color: 'hsl(60, 75%, 60%)', * label: 'Yellow' * }, * { * color: 'hsl(90, 75%, 60%)', * label: 'Light green' * }, * { * color: 'hsl(120, 75%, 60%)', * label: 'Green' * }, * { * color: 'hsl(150, 75%, 60%)', * label: 'Aquamarine' * }, * { * color: 'hsl(180, 75%, 60%)', * label: 'Turquoise' * }, * { * color: 'hsl(210, 75%, 60%)', * label: 'Light blue' * }, * { * color: 'hsl(240, 75%, 60%)', * label: 'Blue' * }, * { * color: 'hsl(270, 75%, 60%)', * label: 'Purple' * } * ] * }; * ``` * * **Note**: The colors are displayed in the `'fontColor'` dropdown. */ colors?: Array<string | ColorOption>; /** * Determines the maximum number of available document colors. * Setting it to `0` will disable the document colors feature. * * By default it equals to the {@link module:font/fontconfig~FontColorConfig#columns} value. * * Examples: * * ```ts * // 1) Neither document colors nor columns are defined in the configuration. * // Document colors will equal 5, * // because the value will be inherited from columns, * // which has a predefined value of 5. * const fontColorConfig = {} * * // 2) Document colors will equal 8, because the value will be inherited from columns. * const fontColorConfig = { * columns: 8 * } * * // 3) Document colors will equal 24, because it has its own value defined. * const fontColorConfig = { * columns: 8, * documentColors: 24 * } * * // 4) The document colors feature will be disabled. * const fontColorConfig = { * columns: 8, * documentColors: 0 * } * ``` */ documentColors?: number; /** * Represents the number of columns in the font color dropdown. * * The default value is: * * ```ts * const fontColorConfig = { * columns: 5 * } * ``` */ columns?: number; /** * Configuration of the color picker feature. * * If set to `false` the picker will not appear. */ colorPicker?: false | ColorPickerConfig; } /** * The configuration of the font family feature. * This option is used by the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} feature. * * ```ts * ClassicEditor * .create( { * fontFamily: ... // Font family feature configuration. * } ) * .then( ... ) * .catch( ... ); * ``` * * See {@link module:core/editor/editorconfig~EditorConfig all editor options}. */ export interface FontFamilyConfig { /** * Available font family options defined as an array of strings. The default value is: * * ```ts * const fontFamilyConfig = { * options: [ * 'default', * 'Arial, Helvetica, sans-serif', * 'Courier New, Courier, monospace', * 'Georgia, serif', * 'Lucida Sans Unicode, Lucida Grande, sans-serif', * 'Tahoma, Geneva, sans-serif', * 'Times New Roman, Times, serif', * 'Trebuchet MS, Helvetica, sans-serif', * 'Verdana, Geneva, sans-serif' * ] * }; * ``` * * which configures 8 font family options. Each option consists of one or more comma–separated font family names. The first font name is * used as the dropdown item description in the UI. * * **Note:** The family names that consist of spaces should not have quotes (as opposed to the CSS standard). The necessary quotes * will be added automatically in the view. For example, the `"Lucida Sans Unicode"` will render as follows: * * ```html * ... * ``` * * The "default" option removes the `fontFamily` attribute from the selection. In such case, the text will * be rendered in the view using the default font family defined in the styles of the web page. * * Font family can be applied using the command API. To do that, use the `fontFamily` command and pass the desired family as a `value`. * For example, the following code will apply the `fontFamily` attribute with the `'Arial'` `value` to the current selection: * * ```ts * editor.execute( 'fontFamily', { value: 'Arial' } ); * ``` * * Executing the `'fontFamily'` command without any value will remove the `fontFamily` attribute from the current selection. */ options?: Array<string | FontFamilyOption>; /** * By default the plugin removes any `font-family` value that does not match the plugin's configuration. * It means that if you paste content with font families that the editor does not understand, the `font-family` attribute * will be removed and the content will be displayed with the default font. * * You can preserve pasted font family values by switching the `supportAllValues` option to `true`: * * ```ts * const fontFamilyConfig = { * supportAllValues: true * }; * ``` * * With this configuration font families not specified in the editor configuration will not be removed when pasting the content. */ supportAllValues?: boolean; } /** * The font family option descriptor. */ export interface FontFamilyOption { /** * The user-readable title of the option. */ title: string; /** * The attribute's unique value in the model. */ model?: string; /** * View element configuration. */ view?: ViewElementDefinition; /** * An array with all matched elements that the view-to-model conversion should also accept. */ upcastAlso?: Array<MatcherPattern>; } /** * The configuration of the font size feature. * This option is used by the {@link module:font/fontsize/fontsizeediting~FontSizeEditing} feature. * * ```ts * ClassicEditor * .create( { * fontSize: ... // Font size feature configuration. * } ) * .then( ... ) * .catch( ... ); * ``` * * See {@link module:core/editor/editorconfig~EditorConfig all editor options}. */ export interface FontSizeConfig { /** * Available font size options. Expressed as predefined presets, numerical "pixel" values * or the {@link module:font/fontconfig~FontSizeOption}. * * The default value is: * * ```ts * const fontSizeConfig = { * options: [ * 'tiny', * 'small', * 'default', * 'big', * 'huge' * ] * }; * ``` * * It defines 4 sizes: **tiny**, **small**, **big**, and **huge**. These values will be rendered as `` elements in the view. * The **default** defines a text without the `fontSize` attribute. * * Each `` has the the `class` attribute set to the corresponding size name. For instance, this is what the **small** size looks * like in the view: * * ```html * ... * ``` * * As an alternative, the font size might be defined using numerical values (either as a `Number` or as a `String`): * * ```ts * const fontSizeConfig = { * options: [ 9, 10, 11, 12, 13, 14, 15 ] * }; * ``` * * Also, you can define a label in the dropdown for numerical values: * * ```ts * const fontSizeConfig = { * options: [ * { * title: 'Small', * model: '8px' * }, * 'default', * { * title: 'Big', * model: '14px' * } * ] * }; * ``` * * Font size can be applied using the command API. To do that, use the `'fontSize'` command and pass the desired font size as a `value`. * For example, the following code will apply the `fontSize` attribute with the **tiny** value to the current selection: * * ```ts * editor.execute( 'fontSize', { value: 'tiny' } ); * ``` * * Executing the `fontSize` command without value will remove the `fontSize` attribute from the current selection. */ options?: Array<string | number | FontSizeOption>; /** * By default the plugin removes any `font-size` value that does not match the plugin's configuration. * It means that if you paste content with font sizes that the editor does not understand, the `font-size` attribute * will be removed and the content will be displayed with the default size. * * You can preserve pasted font size values by switching the `supportAllValues` option to `true`: * * ```ts * const fontSizeConfig = { * options: [ 9, 10, 11, 12, 'default', 14, 15 ], * supportAllValues: true * }; * ``` * * **Note:** This option can only be used with numerical values as font size options. * * With this configuration font sizes not specified in the editor configuration will not be removed when pasting the content. */ supportAllValues?: boolean; } /** * The font size option descriptor. */ export interface FontSizeOption { /** * The user-readable title of the option. */ title: string; /** * The attribute's unique value in the model. */ model?: string; /** * View element configuration. */ view?: ViewElementDefinition; /** * An array with all matched elements that the view-to-model conversion should also accept. */ upcastAlso?: Array<MatcherPattern>; }