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

# Chunk by Title strategy

> The Chunk by Title strategy preserves section boundaries by starting a new chunk whenever a Title element is encountered.

*Type*: `chunk`

*Subtype*: `chunk_by_title`

## Usage guidance

Best general-purpose strategy when your source documents have a clear heading structure.

For more information, see [Chunk by title strategy](/concepts/chunking#chunk-by-title-strategy).

## Settings

<ParamField body="unstructured_api_url" type="string">
  If specified, overrides the default API URL used for chunker calls. Default: none (uses Unstructured's internal default).
</ParamField>

<ParamField body="unstructured_api_key" type="string">
  If specified, overrides the default API key used for chunker calls. Default: none (uses Unstructured's internal default).
</ParamField>

<ParamField body="multipage_sections" type="boolean">
  If `true`, sections can span multiple pages. Default: `false`.
</ParamField>

<ParamField body="combine_text_under_n_chars" type="integer">
  Combines consecutive elements from a section into a single chunk until the section reaches this length in characters. Default: none.
</ParamField>

<ParamField body="include_orig_elements" type="boolean">
  If `true`, the elements used to form a chunk appear in `.metadata.orig_elements` for that chunk. Default: `false`.
</ParamField>

<ParamField body="new_after_n_chars" type="integer">
  Soft maximum length of a chunk in characters. Closes a section after reaching approximately this length. Default: none.
</ParamField>

<ParamField body="max_characters" type="integer">
  Hard maximum number of characters in a chunk. Default: none.
</ParamField>

<ParamField body="overlap" type="integer">
  Number of trailing characters from the prior text-split chunk to prepend to each subsequent chunk formed by splitting an oversized element. Default: none.
</ParamField>

<ParamField body="overlap_all" type="boolean">
  If `true`, applies overlap to chunks formed by combining whole elements, not just oversized ones. Use with caution — this can introduce noise into otherwise clean semantic units. Default: `false`.
</ParamField>

<ParamField body="isolate_table" type="boolean">
  If `true`, each table is placed in its own dedicated chunk, separate from any surrounding
  text elements. If `false`, small tables may share a chunk with adjacent text, producing
  mixed chunks that contain both text and table content.

  Regardless of this setting, narrative overlap is never prepended to table-only chunks,
  and table overlap is never appended to following narrative chunks.

  Note that `max_characters` applies to a chunk's visible `.text` content. When a table
  joins a mixed chunk with `isolate_table` set to `false`, the table's
  `metadata.text_as_html` is not subject to the same size budget. If the table has a large
  HTML representation, the serialized chunk payload may exceed `max_characters`. Use
  `isolate_table: true` if you have strict payload size requirements.

  Default: `true`.
</ParamField>

<ParamField body="contextual_chunking_strategy" type="string" deprecated>
  **Deprecated.** The `v1` contextual chunking option is no longer available in the workflow designer and is not recommended. To apply contextual chunking, add a [Contextual Chunker node](/api-reference/workflow/nodes/enhancement/chunker-chunk-by-contextual) after this chunker. Allowed value: `v1`. Default: none.
</ParamField>

<RequestExample>
  ```python Python SDK theme={null}
  chunk_by_title_chunker_workflow_node = WorkflowNode(
      name="Chunker",
      subtype="chunk_by_title",
      type="chunk",
      settings={
          "unstructured_api_url": None,
          "unstructured_api_key": None,
          "multipage_sections": <True|False>,
          "combine_text_under_n_chars": <combine-text-under-n-chars>,
          "include_orig_elements": <True|False>,
          "new_after_n_chars": <new-after-n-chars>,
          "max_characters": <max-characters>,
          "overlap": <overlap>,
          "overlap_all": <True|False>,
          "isolate_table": <True|False>,
          "contextual_chunking_strategy": "<contextual-chunking-strategy>"
      }
  )
  ```

  ```json cURL theme={null}
  {
      "name": "Chunker",
      "type": "chunk",
      "subtype": "chunk_by_title",
      "settings": {
          "unstructured_api_url": null,
          "unstructured_api_key": null,
          "multipage_sections": <true|false>,
          "combine_text_under_n_chars": <combine-text-under-n-chars>,
          "include_orig_elements": <true|false>,
          "new_after_n_chars": <new-after-n-chars>,
          "max_characters": <max-characters>,
          "overlap": <overlap>,
          "overlap_all": <true|false>,
          "isolate_table": <True|False>,
          "contextual_chunking_strategy": "<contextual-chunking-strategy>"
      }
  }
  ```
</RequestExample>