Word.Font class

Specifies whether the font is formatted as all capital letters, which makes lowercase letters appear as uppercase letters. The possible values are as follows:

• true: All the text has the All Caps attribute.

• false: None of the text has the All Caps attribute.

• null: Returned if some, but not all, of the text has the All Caps attribute.

allCaps: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that indicates whether the font is bold. True if the font is formatted as bold, otherwise, false.

bold: boolean;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Examples

// Bold format text
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a range proxy object for the current selection.
    const selection = context.document.getSelection();

    // Queue a command to make the current selection bold.
    selection.font.bold = true;

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The selection is now bold.');
});

Specifies whether the font is formatted as bold in a right-to-left language document. The possible values are as follows:

• true: All the text is bold.

• false: None of the text is bold.

• null: Returned if some, but not all, of the text is bold.

boldBidirectional: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a BorderUniversalCollection object that represents all the borders for the font.

readonly borders: Word.BorderUniversalCollection;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the color for the specified font. You can provide the value in the '#RRGGBB' format or the color name.

color: string;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Examples

// Change the font color
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a range proxy object for the current selection.
    const selection = context.document.getSelection();

    // Queue a command to change the font color of the current selection.
    selection.font.color = 'blue';

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The font color of the selection has been changed.');
});

Specifies a ColorIndex value that represents the color for the font.

colorIndex: Word.ColorIndex | "Auto" | "Black" | "Blue" | "Turquoise" | "BrightGreen" | "Pink" | "Red" | "Yellow" | "White" | "DarkBlue" | "Teal" | "Green" | "Violet" | "DarkRed" | "DarkYellow" | "Gray50" | "Gray25" | "ClassicRed" | "ClassicBlue" | "ByAuthor";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the color for the Font object in a right-to-left language document.

colorIndexBidirectional: Word.ColorIndex | "Auto" | "Black" | "Blue" | "Turquoise" | "BrightGreen" | "Pink" | "Red" | "Yellow" | "White" | "DarkBlue" | "Teal" | "Green" | "Violet" | "DarkRed" | "DarkYellow" | "Gray50" | "Gray25" | "ClassicRed" | "ClassicBlue" | "ByAuthor";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Specifies whether contextual alternates are enabled for the font.

contextualAlternates: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the color to be used for diacritics for the Font object. You can provide the value in the '#RRGGBB' format.

diacriticColor: string;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies whether Microsoft Word ignores the number of characters per line for the corresponding Font object.

disableCharacterSpaceGrid: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that indicates whether the font has a double strikethrough. True if the font is formatted as double strikethrough text, otherwise, false.

doubleStrikeThrough: boolean;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Specifies whether the font is formatted as embossed. The possible values are as follows:

• true: All the text is embossed.

• false: None of the text is embossed.

• null: Returned if some, but not all, of the text is embossed.

emboss: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies an EmphasisMark value that represents the emphasis mark for a character or designated character string.

emphasisMark: Word.EmphasisMark | "None" | "OverSolidCircle" | "OverComma" | "OverWhiteCircle" | "UnderSolidCircle";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies whether the font is formatted as engraved. The possible values are as follows:

• true: All the text is engraved.

• false: None of the text is engraved.

• null: Returned if some, but not all, of the text is engraved.

engrave: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a FillFormat object that contains fill formatting properties for the font used by the range of text.

readonly fill: Word.FillFormat;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a GlowFormat object that represents the glow formatting for the font used by the range of text.

readonly glow: Word.GlowFormat;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that indicates whether the font is tagged as hidden. True if the font is formatted as hidden text, otherwise, false.

hidden: boolean;

Property Value

Remarks

[ API set: WordApiDesktop 1.2 ]

Specifies the highlight color. To set it, use a value either in the '#RRGGBB' format or the color name. To remove highlight color, set it to null. The returned highlight color can be in the '#RRGGBB' format, an empty string for mixed highlight colors, or null for no highlight color. Note: Only the default highlight colors are available in Office for Windows Desktop. These are "Yellow", "Lime", "Turquoise", "Pink", "Blue", "Red", "DarkBlue", "Teal", "Green", "Purple", "DarkRed", "Olive", "Gray", "LightGray", and "Black". When the add-in runs in Office for Windows Desktop, any other color is converted to the closest color when applied to the font.

highlightColor: string;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Examples

// Highlight selected text
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a range proxy object for the current selection.
    const selection = context.document.getSelection();

    // Queue a command to highlight the current selection.
    selection.font.highlightColor = '#FFFF00'; // Yellow

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The selection has been highlighted.');
});

Specifies a value that indicates whether the font is italicized. True if the font is italicized, otherwise, false.

italic: boolean;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Specifies whether the font is italicized in a right-to-left language document. The possible values are as follows:

• true: All the text is italicized.

• false: None of the text is italicized.

• null: Returned if some, but not all, of the text is italicized.

italicBidirectional: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the minimum font size for which Microsoft Word will adjust kerning automatically.

kerning: number;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the ligature setting for the Font object.

ligature: Word.Ligature | "None" | "Standard" | "Contextual" | "StandardContextual" | "Historical" | "StandardHistorical" | "ContextualHistorical" | "StandardContextualHistorical" | "Discretional" | "StandardDiscretional" | "ContextualDiscretional" | "StandardContextualDiscretional" | "HistoricalDiscretional" | "StandardHistoricalDiscretional" | "ContextualHistoricalDiscretional" | "All";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a LineFormat object that specifies the formatting for a line.

readonly line: Word.LineFormat;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that represents the name of the font.

name: string;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Examples

// Change the font name
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a range proxy object for the current selection.
    const selection = context.document.getSelection();

    // Queue a command to change the current selection's font name.
    selection.font.name = 'Arial';

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The font name has changed.');
});

Specifies the font used for Latin text (characters with character codes from 0 (zero) through 127).

nameAscii: string;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the font name in a right-to-left language document.

nameBidirectional: string;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the East Asian font name.

nameFarEast: string;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the font used for characters with codes from 128 through 255.

nameOther: string;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the number form setting for an OpenType font.

numberForm: Word.NumberForm | "Default" | "Lining" | "OldStyle";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the number spacing setting for the font.

numberSpacing: Word.NumberSpacing | "Default" | "Proportional" | "Tabular";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies if the font is formatted as outlined. The possible values are as follows:

• true: All the text is outlined.

• false: None of the text is outlined.

• null: Returned if some, but not all, of the text is outlined.

outline: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the position of text (in points) relative to the base line.

position: number;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a ReflectionFormat object that represents the reflection formatting for a shape.

readonly reflection: Word.ReflectionFormat;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the scaling percentage applied to the font.

scaling: number;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies if the font is formatted as shadowed. The possible values are as follows:

• true: All the text is shadowed.

• false: None of the text is shadowed.

• null: Returned if some, but not all, of the text is shadowed.

shadow: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that represents the font size in points.

size: number;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Examples

// Change the font size
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a range proxy object for the current selection.
    const selection = context.document.getSelection();

    // Queue a command to change the current selection's font size.
    selection.font.size = 20;

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The font size has changed.');
});

Specifies the font size in points for right-to-left text.

sizeBidirectional: number;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies whether the font is formatted as small caps, which makes lowercase letters appear as small uppercase letters. The possible values are as follows:

• true: All the text has the Small Caps attribute.

• false: None of the text has the Small Caps attribute.

• null: Returned if some, but not all, of the text has the Small Caps attribute.

smallCaps: boolean;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies the spacing between characters.

spacing: number;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that indicates whether the font has a strikethrough. True if the font is formatted as strikethrough text, otherwise, false.

strikeThrough: boolean;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Examples

// Strike format text
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a range proxy object for the current selection.
    const selection = context.document.getSelection();

    // Queue a command to strikethrough the font of the current selection.
    selection.font.strikeThrough = true;

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The selection now has a strikethrough.');
});

Specifies the stylistic set for the font.

stylisticSet: Word.StylisticSet | "Default" | "Set01" | "Set02" | "Set03" | "Set04" | "Set05" | "Set06" | "Set07" | "Set08" | "Set09" | "Set10" | "Set11" | "Set12" | "Set13" | "Set14" | "Set15" | "Set16" | "Set17" | "Set18" | "Set19" | "Set20";

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that indicates whether the font is a subscript. True if the font is formatted as subscript, otherwise, false.

subscript: boolean;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Specifies a value that indicates whether the font is a superscript. True if the font is formatted as superscript, otherwise, false.

superscript: boolean;

Property Value

Remarks

[ API set: WordApi 1.1 ]

Returns a ColorFormat object that represents the color for the font.

readonly textColor: Word.ColorFormat;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a ShadowFormat object that specifies the shadow formatting for the font.

readonly textShadow: Word.ShadowFormat;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Returns a ThreeDimensionalFormat object that contains 3-dimensional (3D) effect formatting properties for the font.

readonly threeDimensionalFormat: Word.ThreeDimensionalFormat;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Specifies a value that indicates the font's underline type. 'None' if the font isn't underlined.

underline: Word.UnderlineType | "Mixed" | "None" | "Hidden" | "DotLine" | "Single" | "Word" | "Double" | "Thick" | "Dotted" | "DottedHeavy" | "DashLine" | "DashLineHeavy" | "DashLineLong" | "DashLineLongHeavy" | "DotDashLine" | "DotDashLineHeavy" | "TwoDotDashLine" | "TwoDotDashLineHeavy" | "Wave" | "WaveHeavy" | "WaveDouble";

Property Value

Remarks

[ API set: WordApi 1.1 ]

Examples

// Underline format text
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a range proxy object for the current selection.
    const selection = context.document.getSelection();

    // Queue a command to underline the current selection.
    selection.font.underline = Word.UnderlineType.single;

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();
    console.log('The selection now has an underline style.');
});

Specifies the color of the underline for the Font object. You can provide the value in the '#RRGGBB' format.

underlineColor: string;

Property Value

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Decreases the font size to the next available size.

decreaseFontSize(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Increases the font size to the next available size.

increaseFontSize(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Word.Interfaces.FontLoadOptions): Word.Font;

Parameters

Returns

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Word.Font;

Parameters

Returns

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Word.Font;

Parameters

Returns

Removes manual character formatting.

reset(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.FontUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

Returns

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Word.Font): void;

Parameters

Returns

Sets the specified font formatting as the default for the active document and all new documents based on the active template.

setAsTemplateDefault(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Word.Font object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.FontData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Word.Interfaces.FontData;

Returns

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you're using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.

track(): Word.Font;

Returns

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You'll need to call context.sync() before the memory release takes effect.

untrack(): Word.Font;

Returns