# `Kreuzberg.Element`
[🔗](https://github.com/kreuzberg-dev/kreuzberg/blob/main/lib/kreuzberg/element.ex#L284)

Semantic element extracted from a document.

Represents a logical unit of content with semantic classification,
unique identifier, and metadata for tracking origin and position.
Compatible with Unstructured.io element format.

## Element Types

Elements are classified into semantic categories:

  * `:title` - Document title
  * `:narrative_text` - Main narrative text body
  * `:heading` - Section heading
  * `:list_item` - List item (bullet, numbered, etc.)
  * `:table` - Table element
  * `:image` - Image element
  * `:page_break` - Page break marker
  * `:code_block` - Code block
  * `:block_quote` - Block quote
  * `:footer` - Footer text
  * `:header` - Header text

## Fields

  * `:element_id` - Unique deterministic identifier for the element
  * `:element_type` - Semantic type classification (atom)
  * `:text` - Text content of the element
  * `:metadata` - ElementMetadata struct with position and source info

## Examples

    iex> element = %Kreuzberg.Element{
    ...>   element_id: "elem-12345",
    ...>   element_type: :narrative_text,
    ...>   text: "This is a paragraph of text.",
    ...>   metadata: %Kreuzberg.ElementMetadata{
    ...>     page_number: 1,
    ...>     filename: "document.pdf"
    ...>   }
    ...> }
    iex> element.element_type
    :narrative_text
    iex> element.text
    "This is a paragraph of text."

# `element_type`

```elixir
@type element_type() ::
  :title
  | :narrative_text
  | :heading
  | :list_item
  | :table
  | :image
  | :page_break
  | :code_block
  | :block_quote
  | :footer
  | :header
```

Semantic element type classification

# `t`

```elixir
@type t() :: %Kreuzberg.Element{
  element_id: String.t(),
  element_type: element_type(),
  metadata: Kreuzberg.ElementMetadata.t(),
  text: String.t()
}
```

# `from_map`

```elixir
@spec from_map(map()) :: t()
```

Creates an Element struct from a map.

Converts a plain map (typically from NIF/Rust) into a proper struct,
handling nested metadata and type conversion.

## Parameters

  * `data` - A map containing element fields

## Returns

An `Element` struct with properly typed fields.

## Examples

    iex> element_map = %{
    ...>   "element_id" => "elem-123",
    ...>   "element_type" => "narrative_text",
    ...>   "text" => "Paragraph content",
    ...>   "metadata" => %{"page_number" => 1}
    ...> }
    iex> element = Kreuzberg.Element.from_map(element_map)
    iex> element.element_type
    :narrative_text

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

Converts an Element struct to a map.

Useful for serialization and passing to external systems.

## Parameters

  * `element` - An `Element` struct

## Returns

A map with string keys representing all fields. Element type is converted to string.

## Examples

    iex> element = %Kreuzberg.Element{
    ...>   element_id: "elem-123",
    ...>   element_type: :narrative_text,
    ...>   text: "Content",
    ...>   metadata: %Kreuzberg.ElementMetadata{}
    ...> }
    iex> map = Kreuzberg.Element.to_map(element)
    iex> map["element_type"]
    "narrative_text"

# `type_description`

```elixir
@spec type_description(element_type()) :: String.t()
```

Returns a human-readable description of the element type.

## Parameters

  * `element_type` - An element type atom

## Returns

A string description of the element type.

## Examples

    iex> Kreuzberg.Element.type_description(:narrative_text)
    "Narrative text"

    iex> Kreuzberg.Element.type_description(:code_block)
    "Code block"

---

*Consult [api-reference.md](api-reference.md) for complete listing*