essentials

Estimated time to read: 12 minutes

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¶

PropsBase

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:744

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¶

PropsSyntaxBase.ToolRequestProps

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:612

Inherited from¶

MultiMedia.ToolRequestProps.id

name¶

name: string

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

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:614

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:746

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¶

PropsSyntaxBase.ToolResponseProps

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:618

Inherited from¶

MultiMedia.ToolResponseProps.id

name¶

name: string

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

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:97

Parameters¶

props¶

PropsWithChildren\<PropsSyntaxBase & AnyProps & object>

Returns¶

Element

Audio()¶

const Audio: (props) => null | Element

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

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:370

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:493

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>

DataObject()¶

const DataObject: (props) => Element

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

DataObject (<obj>, <object>, <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¶

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

const Header: (props) => Element

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

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:650

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:251

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:398

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:529

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:569

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:282

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 />

Paragraph()¶

const Paragraph: (props) => Element

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

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:192

Parameters¶

props¶

PropsWithChildren\<PropsSyntaxAny>

Returns¶

Element

Strikethrough()¶

const Strikethrough: (props) => Element

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

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:340

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:173

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:762

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:805

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:456

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