docx-js/docs/usage/paragraph.md

# Paragraph

> Everything (text, images, graphs etc) in OpenXML is organised in paragraphs.

!> Paragraphs requires an understanding of [Sections](sections.md).

You can create `Paragraphs` in the following ways:

### Shorthand

```ts
import { Paragraph } from "docx";

const paragraph = new Paragraph("Short hand Hello World");
```

### Children Method

This method is useful for adding different [text](text.md) with different styles, [symbols](symbols.md), or adding [images](images.md) inline.

```ts
const paragraph = new Paragraph({
    children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World"), new SymbolRun("F071")],
});
```

### Explicit

```ts
const paragraph = new Paragraph({
    text: "Short hand notation for adding text.",
});
```

After you create the paragraph, you must add the paragraph into the `document's section`. Learn more about `sections` here:

```ts
doc.addSection({
    children: [paragraph],
});
```

Or the preferred convension, define the paragraph inside the section and remove the usage of variables:

```ts
doc.addSection({
    children: [
        new Paragraph({
            children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World")],
        }),
    ],
});
```

## Options

This is the list of options for a paragraph. A detailed explanation is below:

| Property                       | Type                                                                                                                | Mandatory? | Possible Values                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| [text](#text)                  | `string`                                                                                                            | Optional   |                                                                                                            |
| [heading](#heading)            | `HeadingLevel`                                                                                                      | Optional   | `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`, `TITLE`                      |
| [border](#border)              | `IBorderOptions`                                                                                                    | Optional   | `top`, `bottom`, `left`, `right`. Each of these are of type IBorderPropertyOptions. Click here for Example |
| [spacing](#spacing)            | `ISpacingProperties`                                                                                                | Optional   | See below for ISpacingProperties                                                                           |
| [outlineLevel](#outline-level) | `number`                                                                                                            | Optional   |                                                                                                            |
| alignment                      | `AlignmentType`                                                                                                     | Optional   |                                                                                                            |
| heading                        | `HeadingLevel`                                                                                                      | Optional   |                                                                                                            |
| bidirectional                  | `boolean`                                                                                                           | Optional   |                                                                                                            |
| thematicBreak                  | `boolean`                                                                                                           | Optional   |                                                                                                            |
| pageBreakBefore                | `boolean`                                                                                                           | Optional   |                                                                                                            |
| contextualSpacing              | `boolean`                                                                                                           | Optional   |                                                                                                            |
| indent                         | `IIndentAttributesProperties`                                                                                       | Optional   |                                                                                                            |
| keepLines                      | `boolean`                                                                                                           | Optional   |                                                                                                            |
| keepNext                       | `boolean`                                                                                                           | Optional   |                                                                                                            |
| children                       | `(TextRun or PictureRun or Hyperlink)[]`                                                                            | Optional   |                                                                                                            |
| style                          | `string`                                                                                                            | Optional   |                                                                                                            |
| tabStop                        | `{ left?: ITabStopOptions; right?: ITabStopOptions; maxRight?: { leader: LeaderType; }; center?: ITabStopOptions }` | Optional   |                                                                                                            |
| bullet                         | `{ level: number }`                                                                                                 | Optional   |                                                                                                            |
| numbering                      | `{ num: ConcreteNumbering; level: number; custom?: boolean }`                                                       | Optional   |                                                                                                            |

## Text

This is the text in a paragraph. You can also add text by using the `Paragraph` shorthand (mentioned above) or adding `children`.

**Example:**

```ts
const paragraph = new Paragraph({
    text: "Hello World",
});
```

## Heading

**Example:**

Setting a Heading 1 paragraph with "Hello World" as it's text:

```ts
const paragraph = new Paragraph({
    text: "Hello World",
    heading: HeadingLevel.HEADING_1,
});
```

## Border

Add borders to a `Paragraph`. Good for making the `Paragraph` stand out

#### IBorderPropertyOptions

`top`, `bottom`, `left`, `right` of the border

| Property | Type     | Notes    |
| -------- | -------- | -------- |
| color    | `string` | Required |
| space    | `number` | Required |
| value    | `string` | Required |
| size     | `number` | Required |

**Example:**

Add border on the top and the bottom of the paragraph

```ts
const paragraph = new Paragraph({
    text: "I have borders on my top and bottom sides!",
    border: {
        top: {
            color: "auto",
            space: 1,
            value: "single",
            size: 6,
        },
        bottom: {
            color: "auto",
            space: 1,
            value: "single",
            size: 6,
        },
    },
});
```

## Spacing

Adding spacing between paragraphs

### ISpacingProperties

| Property | Type     | Notes    |
| -------- | -------- | -------- |
| after    | `number` | Optional |
| before   | `number` | Optional |
| line     | `number` | Optional |
| lineRule | `string` | Optional |

**Example:**

Add spacing before the paragraph:

```ts
const paragraph = new Paragraph({
    text: "Paragraph with spacing before",
    spacing: {
        before: 200,
    },
});
```

## Outline Level

**Example:**

```ts
const paragraph = new Paragraph({
    outlineLevel: 0,
});
```

## Styles

To create styles, please refer to the styling Wiki: https://github.com/dolanmiu/docx/wiki/Styling

![Word 2013 Styles menu](http://content.gcflearnfree.org/topics/233/style_apply_choose.png "Word 2013 Styles menu")

### Headings and titles

```ts
import { HeadingLevel, Paragraph } from "docx";

const paragraph = new Paragraph({
    text: "Hello World",
    heading: HeadingLevel.TITLE,
});
```

## Text Alignment

To change the text alignment of a paragraph, add an `AlignmentType` option on the paragraph.for center, left, right or justified:

**Example:**

```ts
const paragraph = new Paragraph({
    text: "Hello World",
    heading: HeadingLevel.HEADING_1,
    alignment: AlignmentType.CENTER,
});
```

The above will create a `heading 1` which is `centered`.

### Justified text with breaks

When a paragraph is justified, you may want to not justify the contents of incomplete lines, which end in a soft line break.

![Justified line before](https://user-images.githubusercontent.com/7989576/53820338-e060c680-3f6b-11e9-817c-ecb43271951e.png)

This is possible to achieve using:

```ts
this.doc.Settings.addCompatibility().doNotExpandShiftReturn();
```

The result is:

![Justified line after](https://user-images.githubusercontent.com/7989576/53820344-e2c32080-3f6b-11e9-9afe-24a2ed6e0d78.png)

## Thematic Break

To add a thematic break in the `Paragraph`:

```ts
const paragraph = new docx.Paragraph("Amazing Heading");
const paragraph = new Paragraph({
    text: "Amazing Heading",
    heading: HeadingLevel.HEADING_1,
    thematicBreak: true,
});
```

The above example will create a heading with a page break directly under it.

## Page Break

To move to a new page (insert a page break):

```ts
const paragraph = new docx.Paragraph({
    children: [new TextRun("Amazing Heading"), new PageBreak()],
});
```

The above example will create a heading and start a new page immediately afterwards.

### Page break before:

This option (available in word) will make sure that the paragraph will start on a new page (if it's not already on a new page).

```ts
const paragraph = new Paragraph({
    text: "Hello World on another page",
    pageBreakBefore: true,
});
```

![Page Break Before in Word](https://user-images.githubusercontent.com/34742290/40176503-df3a8398-59db-11e8-8b9c-d719f13aa8b4.png)

Example: https://github.com/dolanmiu/docx/blob/master/demo/15-page-break-before.ts

## Page break control

Paragraphs have `.keepLines()` and `.keepNext()` methods that allow restricting page breaks within and between paragraphs. See [this Microsoft article](https://support.office.com/en-us/article/Keep-lines-and-paragraphs-together-d72af534-926f-4c4b-830a-abfc2daa3bfa) for more details)