Blocks - Prisme.ai

Blocks are reusable UI components that serve as the building blocks for creating interactive interfaces in AI Builder. They encapsulate functionality, emit and listen for events, and can be assembled to create complete user experiences.

Block Fundamentals

What are Blocks?
Block Types
Block Communication

Blocks are modular UI components with specific purposes:

Self-contained: Each block encapsulates specific functionality
Reusable: Can be used across multiple pages and workspaces
Configurable: Customizable through properties and settings
Interactive: Respond to user actions and system events
Event-driven: Communicate with other components through events

Blocks follow the BlockProtocol.org standard, ensuring consistency and interoperability.

Common Block Properties

All blocks share a set of common properties that can be configured in YAML:

Common Properties

slug

string

Required. Unique identifier for the block in your workspace.

onInit

string

Event fired when the block is initialized. Example: myInitBlockEvent

updateOn

string

Event that triggers an update of the block. Example: myUpdateBlockEvent

automation

string

Name of the automation to associate with this block.

sectionId

string

Identifier for the section containing this block. Example: myBlock

className

string

CSS class name to apply to the block. Example: block-classname

css

string

Custom CSS for styling the block. Uses :block selector for the block root element.

:block {
  display: flex;
  max-width: 100%;
  flex: 1;
  flex-direction: column;
}

string

Conditional display expression. Block will only be shown if the expression evaluates to true.

repeat

string

Allows repeating the block for each item in an array. Example: repeat on myArray

item

string

Variable name for the current item when using repeat. Example: myItem

Built-in Blocks Library

AI Builder includes a comprehensive library of built-in blocks. Here’s a detailed reference for each block with its specific YAML configuration.

Form Block

Display an interactive form with validation.

Configuration Options

title

LocalizedText

Optional. Form title.

schema

Schema

Required. JSON Schema defining form fields and validation.

onChange

string | Object

Optional. Event to trigger when form values change.

onSubmit

string | Object

Optional. Event to trigger when form is submitted.

submitLabel

string

Optional. Text for the submit button.

hideSubmit

boolean

Optional. If true, hides the submit button.

disabledSubmit

boolean

Optional. If true, disables the submit button.

disableSubmitDelay

number

Optional. Delay in ms before re-enabling submit button after submission.

values

Record<string, any>

Optional. Initial values for form fields.

buttons

ActionConfig[]

Optional. Additional buttons to display.

collapsed

boolean

Optional. If true, form starts in collapsed state.

autoFocus

boolean

Optional. If true, first field gets focus on form load.

Example YAML

- slug: Form
  title:
    en: Contact Form
    fr: Formulaire de Contact
  schema:
    type: object
    properties:
      name:
        type: string
        title: Name
        minLength: 2
      email:
        type: string
        title: Email
        format: email
      message:
        type: string
        title: Message
        minLength: 10
    required:
      - name
      - email
      - message
  onSubmit: submitContactForm
  submitLabel: Send Message
  disabledSubmit: false
  values:
    name: "{{user.name}}"
    email: "{{user.email}}"
  onInit: myInitBlockForm
  updateOn: myUpdateBlockForm

Learn more about Form Block for advanced configuration: https://docs.prisme.ai/products/ai-builder/workspaces#json-schema-form

RichText Block

Display formatted text with support for Markdown and HTML.

Configuration Options

content

string | LocalizedText

The text content to display. Can be localized with language codes.

markdown

boolean

Optional. If true, content will be parsed as Markdown. Default: false

allowUnsecure

boolean

Optional. If true, allows HTML tags in content. Default: false

tag

string

Optional. HTML tag to use for the container.

Example YAML

- slug: RichText
  content:
    en: <p>Hello World</p>
    fr: <p>Bonjour le Monde</p>
  allowUnsecure: true
  markdown: true
  onInit: myInitBlockRichText
  automation: myAutomation
  updateOn: myUpdateBlockRichText
  sectionId: myBlock
  className: block-classname
  css: |-
    :block {
      display: flex;
      max-width: 100%;
      flex: 1;
      flex-direction: column;
    }

Action Block

Create interactive buttons and links.

Configuration Options

type

string

Required. Action type: ‘external’, ‘internal’, ‘inside’, ‘event’, ‘script’, or ‘upload’.

value

string

Required. Target URL, event name, or script based on type.

text

ReactNode | LocalizedText | Blocks

Required. Button/link text or content.

payload

any

Optional. Data to send with event.

Optional. If true, opens links in a new window.

string

Optional. For upload type, specifies accepted file types.

confirm

Object

Optional. Confirmation dialog settings.

disabled

boolean

Optional. If true, disables the action.

Example YAML

- slug: Action
  text:
    en: Submit Form
    fr: Soumettre le Formulaire
  type: event
  value: submitFormEvent
  payload:
    formId: contactForm
  disabled: "{{!formValid}}"
  confirm:
    label: Are you sure you want to submit?
    yesLabel: Submit
    noLabel: Cancel
  onInit: myInitBlockAction
  updateOn: myUpdateBlockAction
  css: |-
    :block {
      display: inline-flex;
      padding: 8px 16px;
      background-color: #4CAF50;
      color: white;
      border-radius: 4px;
      cursor: pointer;
    }
    :block[disabled] {
      opacity: 0.5;
      cursor: not-allowed;
    }

DataTable Block

Display tabular data with sorting, filtering, and pagination.

Configuration Options

title

LocalizedText

Optional. Table title.

data

Record<string, any>[]

Required. Array of data objects to display.

columns

ColumnDefinition[]

Optional. Column configurations.

pagination

Object

Optional. Pagination configuration.

onSort

string | Object

Optional. Event to trigger when sorting changes.

initialSort

Object

Optional. Initial sort configuration.

bulkActions

Array

Optional. Actions for selected rows.

Optional. Context menu items for rows.

headerContextMenu

MenuItem[]

Optional. Context menu items for column headers.

sticky

boolean

Optional. If true, makes the header sticky.

updateRowOn

string

Optional. Data line update event.
Insert at least one discriminating variable in your event to identify the row to be updated. Ex: “update row $id”

customProps

any

Optional. Additional properties for the table.

Example YAML

- slug: DataTable
  title:
    en: Employee Directory
    fr: Répertoire des Employés
  data: "{{employees}}"
  columns:
    - title: Name
      dataIndex: name
      key: name
      sorter: true
    - title: Email
      dataIndex: email
      key: email
    - title: Department
      dataIndex: department
      key: department
      filters:
        - text: Marketing
          value: marketing
        - text: Engineering
          value: engineering
        - text: HR
          value: hr
  pagination:
    event: changePage
    page: "{{currentPage}}"
    itemCount: "{{totalEmployees}}"
    pageSize: 10
  onSort: sortEmployees
  initialSort:
    by: name
    order: ascend
  sticky: true
  onInit: myInitBlockDataTable
  updateOn: myUpdateBlockDataTable

Image Block

Display an image with optional caption.

Configuration Options

src

string

Optional. URL of the image to display.

alt

string

Optional. Alternative text for the image for accessibility.

caption

LocalizedText

Optional. Caption text to display under the image. Can be localized.

Example YAML

- slug: Image
  src: https://example.com/image.jpg
  alt: Example image
  caption:
    en: An example image caption
    fr: Une légende d'image exemple
  onInit: myInitBlockImage
  updateOn: myUpdateBlockImage
  className: my-image-block
  css: |-
    :block {
      max-width: 100%;
      margin: 1rem 0;
    }
    :block img {
      border-radius: 8px;
    }

Carousel Block

Display a slideshow of multiple blocks.

Configuration Options

blocks

array

Required. Array of blocks to display in the carousel.

autoscroll

object

Optional. Configuration for automatic scrolling.

displayIndicators

boolean

Optional. Whether to display navigation indicators.

blocksClassName

string

Optional. CSS class name to apply to blocks in the carousel.

Example YAML

- slug: Carousel
  blocks:
    - slug: Image
      src: https://example.com/image1.jpg
      alt: First slide
    - slug: Image
      src: https://example.com/image2.jpg
      alt: Second slide
    - slug: Image
      src: https://example.com/image3.jpg
      alt: Third slide
  autoscroll:
    active: true
    speed: 5000
  displayIndicators: true
  blocksClassName: carousel-slide
  onInit: myInitBlockCarousel
  updateOn: myUpdateBlockCarousel

TabsView Block

Display content in tabbed interface.

Configuration Options

tabs

array

Required. Array of tab configurations.

direction

string

Tab direction, either ‘horizontal’ or ‘vertical’.

selected

number

Optional. Index of the initially selected tab.

Example YAML

- slug: TabsView
  direction: horizontal
  selected: 0
  tabs:
    - text: First Tab
      selectedText: First Tab (Selected)
      content:
        blocks:
          - slug: RichText
            content:
              en: Content for the first tab
    - text: Second Tab
      content:
        blocks:
          - slug: RichText
            content:
              en: Content for the second tab
    - text: Action Tab
      type: event
      value: tabActionEvent
      content:
        blocks:
          - slug: RichText
            content:
              en: This tab also triggers an event
  onInit: myInitBlockTabs
  updateOn: myUpdateBlockTabs

Display a sign-in or sign-up form.

Configuration Options

label

string | LocalizedText

Text label for the sign-in button.

boolean

Optional. If true, displays a sign-up form instead of sign-in.

redirect

string

Optional. URL to redirect to after successful authentication.

Example YAML

- slug: Signin
  label:
    en: Sign in to your account
    fr: Connectez-vous à votre compte
  up: false
  redirect: /dashboard
  onInit: myInitBlockSignin
  updateOn: myUpdateBlockSignin

Toast Block

Display notification messages.

Configuration Options

toastOn

string

Event name that triggers the toast notification.

Example YAML

- slug: Toast
  toastOn: showNotification
  onInit: myInitBlockToast
  updateOn: myUpdateBlockToast

Using Toast

The toast block responds to events carrying a message configuration:

// Example event payload for a toast
{
  type: "success", // or "error", "warning", "loading"
  content: {
    en: "Operation completed successfully!",
    fr: "Opération terminée avec succès !"
  },
  duration: 5, // seconds
  key: "unique-toast-id"
}

Hero Block

Display a hero section with title, lead text, and background image.

Configuration Options

title

LocalizedText

Main heading text.

lead

LocalizedText

Subheading or lead paragraph text.

content

BlockContent

Optional. Additional content blocks.

img

string

Background image URL.

backgroundColor

string

Background color (CSS color value).

level

number

Heading level (1-6) for the title.

Example YAML

- slug: Hero
  title:
    en: Welcome to Our Platform
    fr: Bienvenue sur Notre Plateforme
  lead:
    en: Discover the power of AI Builder
    fr: Découvrez la puissance de l'AI Builder
  img: https://example.com/hero-bg.jpg
  backgroundColor: "#f5f5f5"
  level: 1
  content:
    blocks:
      - slug: Action
        text: Get Started
        type: internal
        value: /getting-started
  onInit: myInitBlockHero
  updateOn: myUpdateBlockHero

Display a page footer.

Configuration Options

content

BlocksList

Required. Blocks to display in the footer.

Example YAML

- slug: Footer
  content:
    blocks:
      - slug: RichText
        content:
          en: © 2025 Example Company. All rights reserved.
      - slug: BlocksList
        blocks:
          - slug: Action
            text: Terms
            type: internal
            value: /terms
          - slug: Action
            text: Privacy
            type: internal
            value: /privacy
  onInit: myInitBlockFooter
  updateOn: myUpdateBlockFooter

BlocksList Block

Display a collection of blocks.

Configuration Options

blocks

Array

Required. Array of blocks to render.

blocksClassName

string

Optional. CSS class to apply to all blocks in the list.

tag

string

Optional. HTML tag to use for the container.

fragment

boolean

Optional. If true, renders without a container element.

Example YAML

- slug: BlocksList
  blocks:
    - slug: RichText
      content:
        en: First block in the list
    - slug: RichText
      content:
        en: Second block in the list
    - slug: Image
      src: https://example.com/image.jpg
      alt: Sample image
  blocksClassName: list-item
  tag: div
  onInit: myInitBlocksList
  updateOn: myUpdateBlocksList

Breadcrumbs Block

Display navigation breadcrumbs.

Configuration Options

links

Array

Show Required. Array of links to display.

text

ReactNode | LocalizedText

Link text.

type

string

Action type (‘internal’, ‘external’, etc.).

value

string

Link target based on type.

className

boolean

Optional. Whether to use custom class for this link.

Example YAML

- slug: Breadcrumbs
  links:
    - text: Home
      type: internal
      value: /
    - text: Products
      type: internal
      value: /products
    - text: Product Details
      type: internal
      value: /products/123
      className: true
  onInit: myInitBlockBreadcrumbs
  updateOn: myUpdateBlockBreadcrumbs

Charts Block

Display data visualizations.

Configuration Options

type

string

Required. Chart type: ‘column’, ‘line’, or ‘pie’.

data

Array

Required. Data for the chart (array of arrays).

config

Object

Show Optional. Chart configuration

Object

Show Optional. X-axis configuration.

type

string

Data type for x-axis values.

label

string

Label for x-axis.

Object

Show Optional. Y-axis configuration.

type

string

Data type for y-axis values.

label

string

Label for y-axis.

customProps

Object

Optional. Additional properties for the chart.

Example YAML

- slug: Charts
  type: line
  data:
    - ["Month", "Sales", "Expenses"]
    - ["Jan", 1000, 400]
    - ["Feb", 1500, 460]
    - ["Mar", 1300, 420]
    - ["Apr", 1700, 500]
  config:
    x:
      type: category
      label: Month
    y:
      type: value
      label: Amount ($)
  customProps:
    height: 400
    seriesField: category
    smooth: true
  onInit: myInitBlockCharts
  updateOn: myUpdateBlockCharts

Marketplace Blocks

The following blocks are available after installing specific apps from the marketplace.

Dialog Box Block

Display an interactive chat interface.

Configuration Options

setup

Object

Dialog box setup configuration.

input

Object

Show Input configuration

emojis

boolean

Whether to enable emoji picker.

speechRecognition

boolean

Whether to enable speech recognition.

enabled

boolean

Whether the input is enabled.

disableSubmit

boolean

Whether to disable the submit button.

placeholder

LocalizedText

Placeholder text for input field.

event

string

Event to trigger on input submission.

attachments

any

Attachment configuration.

upload

Object

Upload configuration.

payload

Object

Payload to send with input event.

tools

Object

Tools configuration.

datasources

Object

Data sources configuration.

blocksRight

Array

Blocks to display on the right side of input.

history

Array

Message history to display.

display

Object

Show Display configuration

startAtTop

boolean

Whether to start scrolled to the top.

submitButton

Object

Submit button styling.

sentMessages

Object

Sent message styling.

receivedMessages

Object

Received message styling.

avatar

Object

Avatar styling.

icons

Object

Icon configuration.

Example YAML

- slug: Dialog Box.Dialog Box
  setup:
    input:
      emojis: false
      speechRecognition: false
      enabled: true
      disableSubmit: '{{disableSubmit}}'
      placeholder:
        fr: Message
        en: Message
      event: sendInput
      attachments: '{{attachments}}'
      upload:
        expiresAfter: '{{uploadDuration}}'
        public: false
        shareToken: true
      payload:
        id: '{{conversationId}}'
        agentId: '{{agentId}}'
        thread: '{{currentThread}}'
        model: '{{modelsDropDown.selected.value}}'
        webhookPayload: '{{webhookPayload}}'
        toolsPayload: '{{toolsPayload}}'
      tools:
        list: '{{tools}}'
      datasources:
        list: '{{datasources}}'
      blocksRight:
        - slug: Action
          updateOn: toggleStopMessage
          css: |
            :block svg {
              color: grey;
            }
            :block,
            :block button {
              display: flex;
              justify-content: center;
              align-items: center;
              display: {{stopButtonDisplayMode}}
            }
          text: |
            <svg width="20" role="img" aria-label="stop current message" height="20">
              <rect width="20" height="20" rx="3" ry="3" fill="currentColor"/>
            </svg>
          type: event
          value: stopCurrentMessage
          payload:
            conversationId: '{{conversationId}}'
  history: '{{messages}}'
  display:
    startAtTop: false
    submitButton:
      background: '#015DFF'
    sentMessages:
      background: '#015DFF'
      text: '#ffffff'
      sanitize: true
    receivedMessages:
      background: '#F1F2F7'
      text: '#333'
      sanitize: false
    avatar:
      background: transparent
    icons:
      send: send
      upload: attachment
  css: |
    :block {
      height: 500px;
      border: 1px solid #eee;
      border-radius: 8px;
      overflow: hidden;
    }
  onInit: myInitDialogBox
  updateOn: updateDialogBox

Display content in a floating popover.

Configuration Options

urlFrom

number

URL starting index.

url

string

URL path to load in the popover.

config

Object

Popover configuration.

Show config

header

Object

Header configuration.

button

Object

Button configuration.

Tooltip configuration.

container

Object

Container configuration.

Example YAML

- slug: Popover.Popover
  urlFrom: 0
  url: /form
  config:
    header:
      title: Help Center
      subtitle: Get assistance with your questions
      bgColor: '#4a6cf7'
      icon: https://example.com/icon.svg
    button:
      bgColor: '#4a6cf7'
      icon: https://example.com/button-icon.svg
      position:
        right: 20px
        bottom: 20px
      size:
        width: '120'
        height: '30'
    tooltip:
      text: 'Need help?'
      openDelay: 500
    container:
      animation: opacity
      opened: false
  onInit: myInitPopover
  updateOn: updatePopover

Block Event System

The event system is the core communication mechanism between blocks:

Event Types

Custom Initialization Events

Examples: datatable-block-init, form-block-init

Custom Update Events

Examples: datatable-block-update, chat-block-update

Block-Specific Events

Examples: form-change, block Action (emits an event with payload)

Event Communication Pattern

Event Definition

Blocks define the events they will emit:

- slug: Action
  text: Subscribe
  type: event
  value: user-subscribe
  payload:
    user: id
    product: productId

This creates an event on the system when the end user interacts with blocks

Event Subscription

Other automations register to receive specific events:

when:
  events:
    - user-subscribe
  endpoint: false

This tells the automation to listen for the specified event and call the appropriate handler when it occurs.

Advanced Block Features

Block Composition

Blocks can be composed from other blocks to create higher-level components:

Container Blocks: Wrap and organize other blocks
Composite Blocks: Combine multiple blocks into a cohesive component
Layout Blocks: Control the arrangement of nested blocks
Wrapper Blocks: Add functionality to existing blocks

Composition enables reuse and maintains separation of concerns.

Block Styling

Blocks can be styled through multiple approaches:

CSS Editor: Direct CSS customization
Built-in CSS: Keeping the default CSS
CSS Classes: Predefined style sets

Consistent styling ensures a cohesive user experience.

Block Conditions

Blocks can have conditional behavior based on various logical factors:

Block Display Condition (if): Example: if MyCondition
Repeat Block on Array: Example: repeat on MyTable
Variable Name for Each Item: Example: MyVariable

Conditions enable dynamic, responsive interfaces.

Block Best Practices

Single Responsibility

Design blocks to do one thing well:

Focus on a specific UI function

Avoid creating overly complex blocks

Split complex functionality into multiple blocks

Create specialized blocks for specific use cases

Clear Naming

Use consistent, descriptive naming:

Choose clear, descriptive block names

Use consistent terminology across blocks

Establish naming conventions for properties and events

Document the purpose of each block

Robust Error Handling

Design blocks to handle failures gracefully:

Validate inputs and handle edge cases

Provide clear error states and messages

Implement fallback behavior for missing data

Log issues for troubleshooting

Accessibility

Ensure blocks work for all users:

Follow WCAG guidelines for accessibility

Support keyboard navigation

Include screen reader compatible markup

Maintain sufficient color contrast

Responsive Design

Optimize blocks for all device sizes:

Test across different screen sizes

Implement responsive layouts

Adjust content for mobile displays

Use relative units for sizing

Performance Optimization

Keep blocks efficient and responsive:

Minimize unnecessary renders

Optimize heavy operations

Implement loading states for async operations

Use lazy loading where appropriate

Next Steps

Pages

Learn how to combine blocks into complete user interfaces

Automations

Explore backend logic that interacts with blocks

Framework Architecture

Understand the underlying architecture of AI Builder

Use Cases

See examples of blocks in real-world applications

Overview

AI SecureChat

AI Store

AI Knowledge

AI Builder

AI Governance

AI Collection (beta)

AI Insights (beta)

​Block Fundamentals

​Common Block Properties

​Built-in Blocks Library

​Form Block

​RichText Block

​Action Block

​DataTable Block

​Image Block

​Carousel Block

​TabsView Block

​Signin Block

​Toast Block

​Hero Block

​Footer Block

​BlocksList Block

​Breadcrumbs Block

​Charts Block

​Marketplace Blocks

​Dialog Box Block

​Popover Block

​Block Event System

​Event Types

​Event Communication Pattern

​Advanced Block Features

​Block Best Practices

Single Responsibility

Clear Naming

Robust Error Handling

Accessibility

Responsive Design

Performance Optimization

​Next Steps

Pages

Automations

Framework Architecture

Use Cases

Block Fundamentals

Common Block Properties

Built-in Blocks Library

Form Block

RichText Block

Action Block

DataTable Block

Image Block

Carousel Block

TabsView Block

Signin Block

Toast Block

Hero Block

Footer Block

BlocksList Block

Breadcrumbs Block

Charts Block

Marketplace Blocks

Dialog Box Block

Popover Block

Block Event System

Event Types

Event Communication Pattern

Advanced Block Features

Block Best Practices

Next Steps