useSetParagraphProps
Returns a function that updates the paragraph-wide properties of paragraphs by id: position, wrap width, transformation, indent, alignment, direction, and line height. The text style that varies along the text (font, size, color) is set through useSelectionTextStyle or useProgrammaticEditor.
const setParagraphProps = useSetParagraphProps()
setParagraphProps(paragraphIds, props, options?)props is a ParagraphPropsUpdate: any subset of the ParagraphProps fields below. The omitted fields keep their values.
| Prop | Type | Meaning |
|---|---|---|
x, y | number | The start of the first line's baseline in user space, as if textIndent was 0. It is not a corner of the paragraph box: the box extends above the baseline. |
width | number | 'auto' | The width the text wraps at, in text space units. 'auto' means the paragraph doesn't wrap and widens with its content. |
matrix | ReadonlyMatrix2D | The transformation from text space to user space (scaling, rotation, skewing) around the baseline start, as a PDF matrix [a, b, c, d, e, f]. e and f are ignored: x and y set the position. |
textIndent | number | In text space units, from the start edge of the lines. A positive value indents the first line; a negative value indents all lines but the first (a hanging indent). Clamped to the range the width allows. |
textAlign | TextAlign | 'left', 'center', or 'right'. |
baseDirection | TextDirection | The base writing direction: 'ltr' or 'rtl'. |
lineHeight | number | The distance between the baselines of adjacent lines, in text space units. |
User space is the page coordinate system, in points, with the origin at the bottom-left corner of the page. Text space is the paragraph's own coordinate system: its x axis runs along the baseline, and matrix maps it to user space. With the identity matrix [1, 0, 0, 1, 0, 0], both use the same units.
Behavior
- Props equal to the current values are skipped, so a call that changes nothing creates no undo step.
- Pass
{ excludeFromHistory: true }asoptionsfor changes that must not be undoable. - The call throws
InvalidInputErrorwhen an id doesn't identify an existing paragraph, or a value would break the layout: a non-finite number, a negativewidthorlineHeight, amatrixthat isn't 6 finite numbers or flattens the text (a zero determinant), or an unknowntextAlignorbaseDirection. With no document loaded, it throwsDocumentNotLoadedError. - The current paragraph properties can be read from the
PlainTextParagraphentries of useProgrammaticEditor.
Example
import { useSetParagraphProps } from '@sdk-pdf/react'
function useMakeColumn() {
const setParagraphProps = useSetParagraphProps()
// Wrap the paragraphs at a 240-point column and align them to the right.
return (paragraphIds: string[]) =>
setParagraphProps(paragraphIds, { width: 240, textAlign: 'right' })
}