> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nemu.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Elements

> Document text, rectangles, and images, plus overlay children and z index ordering

The page factories build three primitive elements: text, rectangles, and images. Each is
built with a typed options object and then added to the page or a container. An element joins
the vertical flow unless it carries a `position`, which makes it explicit and absolute.

## Text

```ts theme={null}
interface CreateTextOptions {
  content: string;
  style?: StyleProperties;
  classname?: string;
  width?: number;
  position?: { x: number; y: number };
  parse_markdown?: boolean;
  z_index?: number;
}
```

<ParamField path="content" type="string" required>
  The text to render.
</ParamField>

<ParamField path="style" type="StyleProperties">
  Color, font family, size, weight, alignment, padding, and other style fields.
</ParamField>

<ParamField path="classname" type="string">
  A name a theme can target to apply default styles.
</ParamField>

<ParamField path="width" type="number">
  A fixed width for the text box. Without one, the text takes its intrinsic width.
</ParamField>

<ParamField path="position" type="{ x: number; y: number }">
  Absolute coordinates. With a position the element is explicit and leaves the flow.
</ParamField>

<ParamField path="parse_markdown" type="boolean">
  Overrides the document level markdown setting for this one element.
</ParamField>

<ParamField path="z_index" type="number">
  Draw order among overlapping elements within the same parent.
</ParamField>

## Rectangles

```ts theme={null}
interface CreateRectOptions {
  width?: number;
  height?: number;
  style?: StyleProperties;
  shape_style?: ShapeStyle;
  position?: { x: number; y: number };
  z_index?: number;
}

interface ShapeStyle {
  fill_color?: ColorLike;
  stroke_color?: ColorLike;
  stroke_width?: number;
  border_radius?: number;
}
```

Rectangle colors come from `style.background_color` or from a `shape_style` with
`fill_color` and `stroke_color`. Use `stroke_width` for the border thickness and
`border_radius` for rounded corners.

## Images

```ts theme={null}
interface CreateImageOptions {
  name: string;
  width?: number;
  height?: number;
  position?: { x: number; y: number };
  z_index?: number;
}
```

The `name` references an image registered with `load_image_sync`. Register the file first,
then reference it by name.

## Text, rectangles, and images together

```ts theme={null}
const label = page.text({
  content: "Absolute label",
  position: { x: 100, y: 200 },
  style: { font_size: 11 },
});

const card = page.rect({
  width: 400,
  height: 120,
  shape_style: { fill_color: "#1a365d", border_radius: 10 },
});

pdf.load_image_sync("logo", "./assets/logo.png");
const img = page.image({ name: "logo", width: 120, height: 40 });

page.add(label, card, img);
```

<Note>
  A `position` makes an element explicit and absolute on the page. Without one it joins the
  vertical flow.
</Note>

## Overlay children and z index

Any element can own overlay children built with `element.text`, `element.rect`,
`element.image`, or `element.create_container`. Children are positioned relative to the
parent's top left corner and render on top of it, sorted by z index.

```ts theme={null}
const box = page.rect({
  width: 300,
  height: 80,
  shape_style: { fill_color: "#2b6cb0", border_radius: 8 },
});
box.text({
  content: "Rendered on top of the box.",
  style: { color: "#ffffff", padding: 12 },
  z_index: 1,
});
page.add(box);
```

<Tip>
  Within the same parent, elements render in ascending z index order regardless of declaration
  order.
</Tip>

## Related pages

<CardGroup cols={2}>
  <Card title="Layout" icon="objects-column" href="/packages/pdf/document/layout">
    Arrange elements with flow and flex containers.
  </Card>

  <Card title="Themes" icon="palette" href="/packages/pdf/document/themes">
    Style elements by type and classname.
  </Card>
</CardGroup>