Skip to content

essentials

Estimated time to read: 12 minutes

POML TypeScript API


Interfaces

PropsSyntaxBase

Defined in: packages/poml/essentials.tsx:20

Props base serves the following props subclass, as far as I can now think of: 1. Props for markup basic components 2. Props for serialization basic components 3. Props for essential general components 3.1. Props for other high-level components

Extends

Extended by

Properties

charLimit?

optional charLimit: number

Defined in: packages/poml/base.tsx:143

Soft character limit before truncation is applied.

Inherited from

PropsBase.charLimit

className?

optional className: string

Defined in: packages/poml/base.tsx:128

Inherited from

PropsBase.className

originalEndIndex?

optional originalEndIndex: number

Defined in: packages/poml/base.tsx:133

Inherited from

PropsBase.originalEndIndex

originalStartIndex?

optional originalStartIndex: number

Defined in: packages/poml/base.tsx:132

Inherited from

PropsBase.originalStartIndex

priority?

optional priority: number

Defined in: packages/poml/base.tsx:147

Priority used when truncating globally. Lower numbers are dropped first.

Inherited from

PropsBase.priority

sourcePath?

optional sourcePath: string

Defined in: packages/poml/base.tsx:136

Inherited from

PropsBase.sourcePath

speaker?

optional speaker: Speaker

Defined in: packages/poml/base.tsx:127

Inherited from

PropsBase.speaker

syntax?

optional syntax: string

Defined in: packages/poml/essentials.tsx:21

tokenLimit?

optional tokenLimit: number

Defined in: packages/poml/base.tsx:145

Soft token limit before truncation is applied.

Inherited from

PropsBase.tokenLimit

whiteSpace?

optional whiteSpace: "filter" | "pre" | "trim"

Defined in: packages/poml/base.tsx:140

Inherited from

PropsBase.whiteSpace

writerOptions?

optional writerOptions: object

Defined in: packages/poml/base.tsx:139

Inherited from

PropsBase.writerOptions


ToolRequestProps

Defined in: packages/poml/essentials.tsx:815

Props base serves the following props subclass, as far as I can now think of: 1. Props for markup basic components 2. Props for serialization basic components 3. Props for essential general components 3.1. Props for other high-level components

Extends

Properties

charLimit?

optional charLimit: number

Defined in: packages/poml/base.tsx:143

Soft character limit before truncation is applied.

Inherited from

PropsSyntaxBase.charLimit

className?

optional className: string

Defined in: packages/poml/base.tsx:128

Inherited from

PropsSyntaxBase.className

id

id: string

Defined in: packages/poml/presentation.tsx:683

Inherited from

MultiMedia.ToolRequestProps.id

name

name: string

Defined in: packages/poml/presentation.tsx:684

Inherited from

MultiMedia.ToolRequestProps.name

originalEndIndex?

optional originalEndIndex: number

Defined in: packages/poml/base.tsx:133

Inherited from

PropsSyntaxBase.originalEndIndex

originalStartIndex?

optional originalStartIndex: number

Defined in: packages/poml/base.tsx:132

Inherited from

PropsSyntaxBase.originalStartIndex

parameters

parameters: any

Defined in: packages/poml/presentation.tsx:685

Inherited from

MultiMedia.ToolRequestProps.parameters

priority?

optional priority: number

Defined in: packages/poml/base.tsx:147

Priority used when truncating globally. Lower numbers are dropped first.

Inherited from

PropsSyntaxBase.priority

sourcePath?

optional sourcePath: string

Defined in: packages/poml/base.tsx:136

Inherited from

PropsSyntaxBase.sourcePath

speaker?

optional speaker: Speaker

Defined in: packages/poml/base.tsx:127

Inherited from

PropsSyntaxBase.speaker

syntax?

optional syntax: string

Defined in: packages/poml/essentials.tsx:21

Inherited from

PropsSyntaxBase.syntax

tokenLimit?

optional tokenLimit: number

Defined in: packages/poml/base.tsx:145

Soft token limit before truncation is applied.

Inherited from

PropsSyntaxBase.tokenLimit

whiteSpace?

optional whiteSpace: "filter" | "pre" | "trim"

Defined in: packages/poml/base.tsx:140

Inherited from

PropsSyntaxBase.whiteSpace

writerOptions?

optional writerOptions: object

Defined in: packages/poml/base.tsx:139

Inherited from

PropsSyntaxBase.writerOptions


ToolResponseProps

Defined in: packages/poml/essentials.tsx:817

Props base serves the following props subclass, as far as I can now think of: 1. Props for markup basic components 2. Props for serialization basic components 3. Props for essential general components 3.1. Props for other high-level components

Extends

Properties

charLimit?

optional charLimit: number

Defined in: packages/poml/base.tsx:143

Soft character limit before truncation is applied.

Inherited from

PropsSyntaxBase.charLimit

className?

optional className: string

Defined in: packages/poml/base.tsx:128

Inherited from

PropsSyntaxBase.className

id

id: string

Defined in: packages/poml/presentation.tsx:689

Inherited from

MultiMedia.ToolResponseProps.id

name

name: string

Defined in: packages/poml/presentation.tsx:690

Inherited from

MultiMedia.ToolResponseProps.name

originalEndIndex?

optional originalEndIndex: number

Defined in: packages/poml/base.tsx:133

Inherited from

PropsSyntaxBase.originalEndIndex

originalStartIndex?

optional originalStartIndex: number

Defined in: packages/poml/base.tsx:132

Inherited from

PropsSyntaxBase.originalStartIndex

priority?

optional priority: number

Defined in: packages/poml/base.tsx:147

Priority used when truncating globally. Lower numbers are dropped first.

Inherited from

PropsSyntaxBase.priority

sourcePath?

optional sourcePath: string

Defined in: packages/poml/base.tsx:136

Inherited from

PropsSyntaxBase.sourcePath

speaker?

optional speaker: Speaker

Defined in: packages/poml/base.tsx:127

Inherited from

PropsSyntaxBase.speaker

syntax?

optional syntax: string

Defined in: packages/poml/essentials.tsx:21

Inherited from

PropsSyntaxBase.syntax

tokenLimit?

optional tokenLimit: number

Defined in: packages/poml/base.tsx:145

Soft token limit before truncation is applied.

Inherited from

PropsSyntaxBase.tokenLimit

whiteSpace?

optional whiteSpace: "filter" | "pre" | "trim"

Defined in: packages/poml/base.tsx:140

Inherited from

PropsSyntaxBase.whiteSpace

writerOptions?

optional writerOptions: object

Defined in: packages/poml/base.tsx:139

Inherited from

PropsSyntaxBase.writerOptions

Type Aliases

PropsSyntaxAny

PropsSyntaxAny = PropsSyntaxBase & Serialize.AnyProps

Defined in: packages/poml/essentials.tsx:24

Variables

AnyOrFree()

const AnyOrFree: (props) => Element

Defined in: packages/poml/essentials.tsx:101

Parameters

props

PropsWithChildren\<PropsSyntaxBase & AnyProps & object>

Returns

Element


Audio()

const Audio: (props) => null | Element

Defined in: packages/poml/essentials.tsx:781

Audio (<audio>) embeds an audio file in the content.

Accepts either a file path (src) or base64-encoded audio data (base64). The MIME type can be provided via type or will be inferred from the file extension.

Parameters

props

AudioProps

Returns

null | Element

Examples

<Audio src="path/to/audio.mp3" />
<Audio base64="..." type="audio/wav" />

Bold()

const Bold: (props) => Element

Defined in: packages/poml/essentials.tsx:411

Bold (<b>) emphasizes text in a bold style when using markup syntaxes.

Parameters

props

PropsWithChildren\<PropsSyntaxBase>

Returns

Element

See

Inline for other props available.

Example

<p><b>Task:</b> Do something.</p>

Code()

const Code: (props) => Element

Defined in: packages/poml/essentials.tsx:538

Code is used to represent code snippets or inline code in markup syntaxes.

Parameters

props

PropsWithChildren\<PropsSyntaxBase & AnyProps & InlineProps & CodeProps>

Returns

Element

See

Paragraph for other props available.

Example

<code inline="true">const x = 42;</code>
<code lang="javascript">
const x = 42;
</code>

const Header: (props) => Element

Defined in: packages/poml/essentials.tsx:332

Header (<h>) renders headings in markup syntaxes. It's commonly used to highlight titles or section headings. The header level will be automatically computed based on the context. Use SubContent (<section>) for nested content.

Parameters

props

PropsWithChildren\<PropsSyntaxBase & AnyProps & ParagraphProps>

Returns

Element

See

Paragraph for other props available.

Example

<Header syntax="markdown">Section Title</Header>

Image()

const Image: (props) => null | Element

Defined in: packages/poml/essentials.tsx:710

Image (<img>) displays an image in the content. Alternatively, it can also be shown as an alt text by specifying the syntax prop. Note that syntax must be specified as multimedia to show the image.

Parameters

props

ImageProps

Returns

null | Element

See

Inline for other props available.

Example

<Image src="path/to/image.jpg" alt="Image description" position="bottom" />

Inline()

const Inline: (props) => Element

Defined in: packages/poml/essentials.tsx:274

Inline (<span>) is a container for inline content. When used with markup syntaxes, it wraps text in an inline style, without any preceding or following blank characters. In serializer syntaxes, it's treated as a generic value. Inline elements are not designed to be used alone (especially in serializer syntaxes). One might notice problematic renderings (e.g., speaker not applied) when using it alone.

Parameters

props

PropsWithChildren\<PropsSyntaxBase>

Returns

Element

Example

<p>I'm listening to <span>music</span> right now.</p>

Italic()

const Italic: (props) => Element

Defined in: packages/poml/essentials.tsx:439

Italic (<i>) emphasizes text in an italic style when using markup syntaxes.

Parameters

props

PropsWithChildren\<PropsSyntaxBase>

Returns

Element

See

Inline for other props available.

Example

Your <i>italicized</i> text.

List()

const List: (props) => Element

Defined in: packages/poml/essentials.tsx:581

List (<list>) is a container for multiple ListItem (<item>) elements. When used with markup syntaxes, a bullet or numbering is added.

Parameters

props

PropsWithChildren\<PropsSyntaxBase & AnyProps & ListProps & ParagraphProps>

Returns

Element

See

Paragraph for other props available.

Example

<list listStyle="decimal">
  <item>Item 1</item>
  <item>Item 2</item>
</list>

ListItem()

const ListItem: (props) => Element

Defined in: packages/poml/essentials.tsx:622

ListItem (<item>) is an item within a List component. In markup mode, it is rendered with the specified bullet or numbering style.

Parameters

props

PropsWithChildren\<PropsSyntaxBase & AnyProps & ParagraphProps>

Returns

Element

See

Paragraph for other props available.

Example

<list listStyle="decimal">
  <item blankLine="true">Item 1</item>
  <item>Item 2</item>
</list>

Newline()

const Newline: (props) => null | Element

Defined in: packages/poml/essentials.tsx:307

Newline (<br>) explicitly adds a line break, primarily in markup syntaxes. In serializer syntaxes, it's ignored.

Parameters

props

PropsSyntaxBase & NewlineProps

Returns

null | Element

See

Inline for other props available.

Example

<br />

Object()

const Object: (props) => Element

Defined in: packages/poml/essentials.tsx:663

Object (<obj>, <dataObj>) displays external data or object content. When in serialize mode, it's serialized according to the given serializer.

Parameters

props

PropsWithChildren\<PropsSyntaxBase & ObjectProps>

Returns

Element

See

Inline for other props available.

Example

<Object syntax="json" data="{ key: 'value' }" />

Paragraph()

const Paragraph: (props) => Element

Defined in: packages/poml/essentials.tsx:223

Paragraph (<p>) is a standalone section preceded by and followed by two blank lines in markup syntaxes. It's mostly used for text contents.

Parameters

props

PropsWithChildren\<PropsSyntaxBase & AnyProps & ParagraphProps>

Returns

Element

See

Text for other props available.

Example

<p>Contents of the paragraph.</p>

Poml()

const Poml: (props) => Element = Text

Defined in: packages/poml/essentials.tsx:208

Parameters

props

PropsWithChildren\<PropsSyntaxAny>

Returns

Element


Strikethrough()

const Strikethrough: (props) => Element

Defined in: packages/poml/essentials.tsx:469

Strikethrough (<s>, <strike>) indicates removed or invalid text in markup syntaxes.

Parameters

props

PropsWithChildren\<PropsSyntaxBase>

Returns

Element

See

Inline for other props available.

Example

<s>This messages is removed.</s>

SubContent()

const SubContent: (props) => Element

Defined in: packages/poml/essentials.tsx:374

SubContent (<section>) renders nested content, often following a header. The headers within the section will be automatically adjusted to a lower level.

Parameters

props

PropsWithChildren\<PropsSyntaxBase & AnyProps & ParagraphProps>

Returns

Element

See

Paragraph for other props available.

Example

<h>Section Title</h>
<section>
  <h>Sub-section Title</h>  <!-- Nested header -->
  <p>Sub-section details</p>
</section>

Text()

const Text: (props) => Element

Defined in: packages/poml/essentials.tsx:180

Text (<text>, <poml>) is a wrapper for any contents. By default, it uses markdown syntax and writes the contents within it directly to the output. When used with "markup" syntaxes, it renders a standalone section preceded and followed by one blank line. It's mostly used in the root element of a prompt, but it should also work in any other places. This component will be automatically added as a wrapping root element if it's not provided: 1. If the first element is pure text contents, <poml syntax="text"> will be added. 2. If the first element is a POML component, <poml syntax="markdown"> will be added.

Parameters

props

PropsWithChildren\<PropsSyntaxAny>

Returns

Element

Example

<poml syntax="text">
Contents of the whole prompt.

1. Your customized list.
2. You don't need to know anything about POML.
</poml>

To render the whole prompt in markdown syntax with a "human" speaker:

<poml syntax="markdown" speaker="human">
  <p>You are a helpful assistant.</p>
  <p>What is the capital of France?</p>
</poml>

Experimental usage with limits and priority:

<poml syntax="markdown" tokenLimit="10">
  <p priority="1">This has lower priority and may be truncated first.</p>
  <p priority="3">This has higher priority and will be preserved longer.</p>
</poml>

ToolRequest()

const ToolRequest: (props) => Element

Defined in: packages/poml/essentials.tsx:833

ToolRequest represents an AI-generated tool request with parameters. Used to display tool calls made by AI models.

Parameters

props

ToolRequestProps

Returns

Element

Example

<ToolRequest id="123" name="search" parameters={{ query: "hello" }} />

ToolResponse()

const ToolResponse: (props) => Element

Defined in: packages/poml/essentials.tsx:885

ToolResponse represents the result of a tool execution. Used to display tool execution results with rich content.

Parameters

props

PropsWithChildren\<ToolResponseProps>

Returns

Element

Example

<ToolResponse id="123" name="search">
 <Paragraph>Search results for "hello":</Paragraph>
 <List>
  <ListItem>Result 1</ListItem>
  <ListItem>Result 2</ListItem>
 </List>
</ToolResponse>

Underline()

const Underline: (props) => Element

Defined in: packages/poml/essentials.tsx:499

Underline (<u>) draws a line beneath text in markup syntaxes.

Parameters

props

PropsWithChildren\<PropsSyntaxBase>

Returns

Element

See

Inline for other props available.

Example

This text is <u>underlined</u>.

Functions

computeSyntaxContext()

computeSyntaxContext(props, defaultSyntax?, invalidPresentations?): Presentation

Defined in: packages/poml/essentials.tsx:34

Parameters

props

PropsSyntaxBase

defaultSyntax?

string

invalidPresentations?

string[]

Returns

Presentation