# Styling

Source: https://docx-editor.portone.io/docs/styling

The stylesheet, the CSS custom properties an application may set, and font fallbacks.

Import the stylesheet once; it includes the ProseMirror base styles:

```ts
import "@portone/docx-editor/styles.css";
```

The paper itself (page size, margins, default font, and line height) comes from the open document,
not from the stylesheet.

## The frame [#the-frame]

The editor's outer frame has a neutral border and rounded corners, read from custom properties:

```css
.my-editor {
  --docx-editor-border: none;
  --docx-editor-radius: 0;
}
```

Pass the class through `className`, or set the properties on any ancestor.
`style` reaches the same frame, which is where a height comes from when the layout does not give
one.

## Properties you may set [#properties-you-may-set]

| Property                                  | Default                      | What it controls                                                                                                                                                                               |
| ----------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--docx-editor-border`                    | `1px solid rgb(0 0 0 / 12%)` | The frame's border. `none` removes it.                                                                                                                                                         |
| `--docx-editor-radius`                    | `12px`                       | The frame's corner radius.                                                                                                                                                                     |
| `--docx-editor-comments-width`            | `320px`                      | The width of the comment rail. The package narrows it to 240, 200, and 180 pixels as the viewport crosses 840, 720, and 560 pixels, so an override for small screens needs a query of its own. |
| `--docx-editor-horizontal-scrollbar-size` | `10px`                       | The space kept clear below the comment rail for the horizontal scrollbar a zoomed page brings.                                                                                                 |
| `--docx-editor-empty-run-width`           | `1em`                        | The width of the box drawn for a [highlighted or shaded run with no text](https://docx-editor.portone.io/docs/features/text-and-paragraphs.md#text-formatting), a blank left to fill in.                                        |

## Locked content and content controls [#locked-content-and-content-controls]

Content a lock shuts is drawn with a yellow tint, an orange outline, and a not-allowed pointer. A
content control whose contents stay editable is not marked.
Four properties change that, for inline fields, whole paragraphs or tables, cells, and rows alike:

| Property                           | Default                 | What it controls                                                                                 |
| ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
| `--docx-editor-locked-background`  | `rgb(255 235 59 / 50%)` | The tint over locked content, which reads as `#fff59d` on white paper. `transparent` removes it. |
| `--docx-editor-locked-outline`     | `1px solid #f9a825`     | The outline around locked content, as an `outline` value. `none` removes it.                     |
| `--docx-editor-control-background` | `transparent`           | The tint over a content control that stays editable.                                             |
| `--docx-editor-control-outline`    | `none`                  | The outline around such a control.                                                               |

For example, to draw what the reader cannot change in grey and the fields they fill in in yellow:

```css
.my-editor {
  --docx-editor-locked-background: rgb(0 0 0 / 6%);
  --docx-editor-locked-outline: 1px dashed rgb(0 0 0 / 50%);
  --docx-editor-control-background: rgb(255 235 59 / 50%);
}
```

The tint is painted over the document's own shading rather than in place of it, so a translucent
color keeps a shaded cell's color visible beneath it. A run's own shading or highlight is painted
over the tint, and the outline still marks the control there.
An editable control inside locked content is drawn as the locked content around it, since the lock
holds there too.
A color close to the document's own highlighting makes the two hard to tell apart, and an outline
with less than 3:1 contrast against the paper is hard to see; weigh both when choosing a theme.

## Properties the editor writes [#properties-the-editor-writes]

The editor also sets properties of its own, measured from the open document: `--docx-editor-zoom`,
the page size and margins, the default font and line height, and the marker and tab widths.
Read them if a control of yours sits beside the paper; do not set them.
[Zoom](https://docx-editor.portone.io/docs/editor-api/zoom.md) covers the zoom props.

## Font fallbacks [#font-fallbacks]

The editor keeps each declared font name first and appends a fallback stack, so a font missing
from the reader's machine lands on one of the right shape.
The built-in set knows the CJK and Latin office font names and ends on a Latin sans.
Pass `fontFallbacks` to stand different fonts in:

```tsx
import {
  DEFAULT_FONT_FALLBACKS,
  DocxEditor,
  type FontFallbacks,
} from "@portone/docx-editor";

const fallbacks: FontFallbacks = {
  groups: [{ stack: '"Inter", sans-serif', names: ["arial", "helvetica"] }],
  defaultStack: '"Inter", sans-serif',
  defaultFontName: "Inter",
};

const author = { id: user.id, name: user.name };

<DocxEditor
  document={file}
  mode={{ kind: "edit", author }}
  fontFallbacks={fallbacks}
/>;
```

Every name in a group is drawn with the group's stack, matched ignoring letter case.
`defaultStack` covers a name in no group and a document that declares no font, and
`defaultFontName` is the name the toolbar shows in that case.
`DEFAULT_FONT_FALLBACKS` is exported for a set built by extending the built-in one.

The package names fonts and never downloads them; the built-in Korean stacks name Pretendard
first, but loading it is the application's business.
Fallbacks affect display only; the exported document keeps the fonts it declared.
The paragraph style picker and the HTML written to the clipboard keep the built-in set.