Props

Properties are used in actions and triggers to collect information from the user. They are also displayed to the user for input. Each property renders as a labelled field in the step settings form; the previews below show exactly what the user sees.

Basic Properties

These properties collect basic information from the user.

Short Text

This property collects a short text input from the user.

Property.ShortText({
  displayName: 'Name',
  description: 'Enter your name',
  required: true,
  defaultValue: 'John Doe',
  placeholder: 'Enter your name',
});

Long Text

This property collects a long text input from the user.

Property.LongText({
  displayName: 'Description',
  description: 'Enter a description',
  required: false,
});

Rich Text

This property gives the user a formatting toolbar (bold, italic, underline, links, lists) and preserves {{ variables }} inserted from previous steps. Pair it with a sibling dropdown via formatProperty to let the user switch between plain text and HTML; the returned value is a plain string in the chosen format.

props: {
  body_type: Property.StaticDropdown({
    displayName: 'Body Type',
    required: true,
    defaultValue: 'plain_text',
    display: 'cards',
    options: {
      options: [
        { label: 'Plain text', value: 'plain_text', description: 'Simple', icon: 'text' },
        { label: 'HTML', value: 'html', description: 'Rich + styled', icon: 'code' },
      ],
    },
  }),
  body: Property.RichText({
    displayName: 'Body',
    description: 'Body of the email',
    required: true,
    // Name of the sibling dropdown whose value selects the editing mode.
    formatProperty: 'body_type',
  }),
}

formatProperty maps the sibling value by convention: plain_text / plain / text → plain, html → rich HTML, markdown / md → markdown. Anything else falls back to plain.

Checkbox

This property presents a toggle for the user to switch on or off.

Property.Checkbox({
  displayName: 'Agree to Terms',
  description: 'Check this box to agree to the terms',
  required: true,
  defaultValue: false,
});

You can also reveal nested fields only when the checkbox is on by listing their names in reveals. The revealed fields appear indented beneath the toggle.

props: {
  has_attachment: Property.Checkbox({
    displayName: 'Has attachment',
    description: 'Only match emails with a file',
    required: false,
    defaultValue: false,
    reveals: ['attachment_name'],
  }),
  attachment_name: Property.ShortText({
    displayName: 'Attachment name',
    required: false,
    placeholder: 'e.g. invoice.pdf',
  }),
}

Markdown

This property displays a markdown snippet to the user, useful for documentation or instructions. It includes a variant option to style the markdown, using the MarkdownVariant enum:

BORDERLESS: For a minimalistic, no-border layout.
INFO: Displays informational messages.
WARNING: Alerts the user to cautionary information.
TIP: Highlights helpful tips or suggestions.

The default value for variant is INFO.

Property.MarkDown({
    value: '## This is a markdown snippet',
    variant: MarkdownVariant.WARNING,
}),

If you want to show a webhook url to the user, use {{ webhookUrl }} in the markdown snippet.

DateTime

This property collects a date and time from the user.

Property.DateTime({
  displayName: 'Date and Time',
  description: 'Select a date and time',
  required: true,
  defaultValue: '2023-06-09T12:00:00Z',
});

Date Range

This property collects a relative or absolute time window. The user picks a preset (last 24 hours, 7 / 30 / 90 days, this month) or a custom range with explicit after / before dates. Set display: 'dropdown' to render the presets as a compact select (used inside the filter builder); omit it for pill buttons.

Property.DateRange({
  displayName: 'Date',
  description: 'Limit results to a time window',
  required: false,
  display: 'dropdown',
});

The value is { preset, after?, before? }. Resolve it to concrete ISO bounds inside run() with dateRangeUtils.resolve. Relative presets resolve against “now”, so recurring flows roll the window forward:

import { dateRangeUtils } from '@activepieces/pieces-framework';

const { after, before } = dateRangeUtils.resolve(context.propsValue.date_range);
// after / before are ISO strings (or undefined for an open bound)

Number

This property collects a numeric input from the user.

Property.Number({
  displayName: 'Quantity',
  description: 'Enter a number',
  required: true,
});

Set display: 'stepper' with min / max / step to render a compact −/value/+ control for bounded numbers.

Property.Number({
  displayName: 'Max results',
  required: false,
  defaultValue: 10,
  display: 'stepper',
  min: 1,
  max: 500,
  step: 1,
});

This property presents a dropdown menu with predefined options.

Property.StaticDropdown({
  displayName: 'Country',
  description: 'Select your country',
  required: true,
  options: {
    options: [
      {
        label: 'Option One',

        value: '1',
      },
      {
        label: 'Option Two',
        value: '2',
      },
    ],
  },
});

For a small set of choices, set display: 'cards' to render the options as selectable cards. Each option may carry an icon and a short description.

Property.StaticDropdown({
  displayName: 'Body Type',
  required: true,
  defaultValue: 'plain_text',
  display: 'cards',
  options: {
    options: [
      { label: 'Plain text', value: 'plain_text', description: 'Simple', icon: 'text' },
      { label: 'HTML', value: 'html', description: 'Rich + styled', icon: 'code' },
    ],
  },
});

This property presents a dropdown menu with multiple selection options.

Property.StaticMultiSelectDropdown({
  displayName: 'Colors',
  description: 'Select one or more colors',
  required: true,
  options: {
    options: [
      {
        label: 'Red',
        value: 'red',
      },
      {
        label: 'Green',
        value: 'green',
      },
      {
        label: 'Blue',
        value: 'blue',
      },
    ],
  },
});

JSON

This property collects JSON data from the user.

Property.Json({
  displayName: 'Data',
  description: 'Enter JSON data',
  required: true,
  defaultValue: { key: 'value' },
});

Dictionary

This property collects key-value pairs from the user.

Property.Object({
  displayName: 'Options',
  description: 'Enter key-value pairs',
  required: true,
  defaultValue: {
    key1: 'value1',
    key2: 'value2',
  },
});

File

This property collects a file from the user, either by providing a URL or uploading a file.

Property.File({
  displayName: 'File',
  description: 'Upload a file',
  required: true,
});

Color

This property collects a color from the user via a swatch and hex input.

Property.Color({
  displayName: 'Brand color',
  description: 'Pick a color',
  required: false,
});

Array of Strings

This property collects an array of strings from the user.

Property.Array({
  displayName: 'Tags',
  description: 'Enter tags',
  required: false,
  defaultValue: ['tag1', 'tag2'],
});

Array of Fields

This property collects an array of objects from the user.

Property.Array({
  displayName: 'Fields',
  description: 'Enter fields',
  properties: {
    fieldName: Property.ShortText({
      displayName: 'Field Name',
      required: true,
    }),
    fieldType: Property.StaticDropdown({
      displayName: 'Field Type',
      required: true,
      options: {
        options: [
          { label: 'TEXT', value: 'TEXT' },
          { label: 'NUMBER', value: 'NUMBER' },
        ],
      },
    }),
  },
  required: false,
  defaultValue: [],
});

Dynamic Data Properties

These properties provide more advanced options for collecting user input. This property allows for dynamically loaded options based on the user’s input.

Property.Dropdown({
  displayName: 'Options',
  description: 'Select an option',
  required: true,
  auth: yourPieceAuth,
  refreshers: ['auth'],
  refreshOnSearch: false,
  options: async ({ auth }, { searchValue }) => {
    // Search value only works when refreshOnSearch is true
    if (!auth) {
      return {
        disabled: true,
      };
    }
    return {
      options: [
        {
          label: 'Option One',
          value: '1',
        },
        {
          label: 'Option Two',
          value: '2',
        },
      ],
    };
  },
});

When accessing the Piece auth, be sure to use exactly auth as it is hardcoded. However, for other properties, use their respective names.

This property allows for multiple selections from dynamically loaded options.

Property.MultiSelectDropdown({
  displayName: 'Options',
  description: 'Select one or more options',
  required: true,
  refreshers: ['auth'],
  auth: yourPieceAuth,
  options: async ({ auth }) => {
    if (!auth) {
      return {
        disabled: true,
      };
    }
    return {
      options: [
        {
          label: 'Option One',
          value: '1',
        },
        {
          label: 'Option Two',
          value: '2',
        },
      ],
    };
  },
});

When accessing the Piece auth, be sure to use exactly auth as it is hardcoded. However, for other properties, use their respective names.

Dynamic Properties

This property is used to construct forms dynamically based on API responses or user input.

import {
	httpClient,
	HttpMethod,
} from '@activepieces/pieces-common';


Property.DynamicProperties({
  description: 'Dynamic Form',
  displayName: 'Dynamic Form',
  required: true,
  refreshers: ['auth'],
  auth: yourPieceAuth,
  props: async ({auth}) => {
    const apiEndpoint = 'https://someapi.com';
    const response = await httpClient.sendRequest<{ values: [string[]][] }>({
        method: HttpMethod.GET,
        url: apiEndpoint ,
        //you can add the auth value to the headers
	  });

    const properties = {
      prop1: Property.ShortText({
        displayName: 'Property 1',
        description: 'Enter property 1',
        required: true,
      }),
      prop2: Property.Number({
        displayName: 'Property 2',
        description: 'Enter property 2',
        required: false,
      }),
    };

    return properties;
  },
});

Layout & display options

Every property accepts a few optional hints that fine-tune how it renders. They are ignored where they don’t apply, so they’re always safe to add.

Hint	Applies to	Effect
`placeholder`	text inputs	Grey hint text shown inside an empty field (e.g. `you@example.com`).
`width: 'half'`	any prop inside a group	Renders two fields side-by-side instead of full-width.
`icon`	any prop	A named icon shown beside the field in the filter builder.
`advanced: true`	any prop	Moves the field into the collapsible Advanced section. Props render in the main form by default.

Every property renders in the main form by default, required or not. Set advanced: true on a secondary option to tuck it into the collapsible Advanced section; advanced: false is the default and has no effect. Avoid the flag on required props: the section starts collapsed, so a mandatory field hidden there only surfaces as a validation error. Half-width fields

props: {
  first_name: Property.ShortText({ displayName: 'First name', required: false, width: 'half' }),
  last_name: Property.ShortText({ displayName: 'Last name', required: false, width: 'half' }),
}

Grouping properties

Actions and triggers can declare propertyGroups to organize related fields. Each group references its members by name and chooses how they render with display.

Segmented tabs

display: 'tabs' groups a set of props into a segmented tab control, for example To / Cc / Bcc recipients.

createAction({
  // ...
  propertyGroups: [
    {
      key: 'recipients',
      display: 'tabs',
      label: 'Recipients',
      description: 'Who receives this email. Use Cc and Bcc for additional recipients.',
      props: ['to', 'cc', 'bcc'],
    },
  ],
  props: {
    to: Property.Array({ displayName: 'To', required: true }),
    cc: Property.Array({ displayName: 'Cc', required: false }),
    bcc: Property.Array({ displayName: 'Bcc', required: false }),
  },
});

Filter builder

For search / list actions, display: 'builder' renders a progressive “Add filter” builder: the user starts with an empty step and adds only the filters they need from a searchable, categorized picker. Each builder group becomes a picker category; a footer group pins a control (such as a result limit) below the list.

createAction({
  // ...
  propertyGroups: [
    { key: 'people',  display: 'builder', label: 'People',  icon: 'users',    props: ['from', 'to'] },
    { key: 'time',    display: 'builder', label: 'Time',    icon: 'calendar', props: ['date_range'] },
    { key: 'footer',  display: 'footer',  props: ['max_results'] },
  ],
  props: {
    from: Property.ShortText({ displayName: 'From', required: false, icon: 'user', placeholder: 'sender@example.com' }),
    to: Property.ShortText({ displayName: 'To', required: false, icon: 'send', placeholder: 'recipient@example.com' }),
    date_range: Property.DateRange({ displayName: 'Date', required: false, display: 'dropdown', icon: 'calendar' }),
    max_results: Property.Number({ displayName: 'Max results', required: false, defaultValue: 10, display: 'stepper', min: 1, max: 500 }),
  },
});

A filter row is shown when its value is set, so there’s nothing extra to persist. Give filters short placeholder hints and an icon so each row reads clearly. Note that a builder or footer group also switches off the Advanced section for the whole step: every prop lives in the builder.

Sectioned cards

display: 'section' groups related props into titled cards, for example a Send to card and a Message card. Unlike tabs and the filter builder, sectioned layouts keep the collapsible Advanced section for props outside the cards: an ungrouped prop still honours advanced: true, unless it is a checkbox reveals target, which renders inline under its toggle instead. Props inside a section are always essential. Give each group a label and icon, and use width: 'half' on members to pack two fields per row.

createAction({
  // ...
  propertyGroups: [
    { key: 'destination', display: 'section', label: 'Send to', icon: 'send', props: ['chat_id'] },
    { key: 'message',     display: 'section', label: 'Message',  icon: 'text', props: ['format', 'message'] },
  ],
  props: {
    chat_id: Property.ShortText({ displayName: 'Chat Id', required: true, placeholder: '@channelusername or 123456789' }),
    format: Property.StaticDropdown({ displayName: 'Format', required: false, display: 'cards', options: { options: [/* Markdown / HTML / Plain */] } }),
    message: Property.RichText({ displayName: 'Message', required: true, formatProperty: 'format' }),
    // ungrouped props can opt into Advanced with advanced: true
    disable_notification: Property.Checkbox({ displayName: 'Disable notification', required: false, advanced: true }),
  },
});

Custom Property (BETA)

This feature is still in BETA and not fully released yet, please let us know if you use it and face any issues and consider it a possibility could have breaking changes in the future

This is a property that lets you inject JS code into the frontend and manipulate the DOM of this content however you like, it is extremely useful in case you are embedding Activepieces and want to have a way to communicate with the SaaS embedding it. It has a code property which is a function that takes in an object parameter which will have the following schema:

Parameter Name	Type	Description
onChange	`(value:unknown)=>void`	A callback you call to set the value of your input (only call this inside event handlers)
value	`unknown`	Whatever the type of the value you pass to onChange
containerId	`string`	The ID of an HTML element in which you can modify the DOM however you like
isEmbedded	`boolean`	The flag that tells you if the code is running inside an embedded instance of Activepieces
projectId	`string`	The project ID of the flow the step that contains this property is in
disabled	`boolean`	The flag that tells you whether or not the property is disabled
property	`{ displayName:string, description?: string, required: boolean}`	The current property information

You can return a clean up function at the end of the code property function to remove any listeners or HTML elements you inserted (this is important for development mode, the component gets mounted twice).
This function must be pure without any imports from external packages or variables outside the function scope.
Must mark your piece minimumSupportedRelease property to be at least 0.58.0 after introducing this property to it.

Here is how to define such a property:

 Property.Custom({
      code:(({value,onChange,containerId})=>{
        const container = document.getElementById(containerId);
        const input = document.createElement('input');
        input.classList.add(...['border','border-solid', 'border-border', 'rounded-md']) 
        input.type = 'text';
        input.value = `${value}`;
        input.oninput = (e: Event) => {
          const value = (e.target as HTMLInputElement).value;
          onChange(value);
        }
       container!.appendChild(input);
       const windowCallback = (e:MessageEvent<{type:string,value:string,propertyName:string}>) => {
        if(e.data.type === 'updateInput' && e.data.propertyName === 'YOUR_PROPERTY_NAME'){
          input.value= e.data.value;
          onChange(e.data.value);
        }
       }
       window.addEventListener('message', windowCallback);
        return ()=>{
          window.removeEventListener('message', windowCallback);
          container!.removeChild(input);
        }
      }),
      displayName: 'Custom Property',
      required: true
    })

If you would like to know more about how to setup communication between Activepieces and the SaaS that’s embedding it, check the window postMessage API.

Build a Piece

Piece Reference

Misc

Basic Properties

Short Text

Long Text

Rich Text

Checkbox

Markdown

DateTime

Date Range

Number

JSON

Dictionary

File

Color

Array of Strings

Array of Fields

Dynamic Data Properties

Dynamic Properties

Layout & display options

Grouping properties

Segmented tabs

Filter builder

Sectioned cards

Custom Property (BETA)

​Basic Properties

​Short Text

​Long Text

​Rich Text

​Checkbox

​Markdown

​DateTime

​Date Range

​Number

​Static Dropdown

​Static Multiple Dropdown

​JSON

​Dictionary

​File

​Color

​Array of Strings

​Array of Fields

​Dynamic Data Properties

​Dropdown

​Multi-Select Dropdown

​Dynamic Properties

​Layout & display options

​Grouping properties

​Segmented tabs

​Filter builder

​Sectioned cards

​Custom Property (BETA)

Basic Properties

Short Text

Long Text

Rich Text

Checkbox

Markdown

DateTime

Date Range

Number

Static Dropdown

Static Multiple Dropdown

JSON

Dictionary

File

Color

Array of Strings

Array of Fields

Dynamic Data Properties

Dropdown

Multi-Select Dropdown

Dynamic Properties

Layout & display options

Grouping properties

Segmented tabs

Filter builder

Sectioned cards

Custom Property (BETA)