ContextQMD
Back to Activepieces

Props

docs/build-pieces/piece-reference/properties.mdx

0.82.110.4 KB
Original Source

Properties are used in actions and triggers to collect information from the user. They are also displayed to the user for input. Here are some commonly used properties:

Basic Properties

These properties collect basic information from the user.

Short Text

This property collects a short text input from the user.

Example:

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

Long Text

This property collects a long text input from the user.

Example:

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

Checkbox

This property presents a checkbox for the user to select or deselect.

Example:

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

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.

Example:

typescript
Property.MarkDown({
    value: '## This is a markdown snippet',
    variant: MarkdownVariant.WARNING,
}),
<Tip> If you want to show a webhook url to the user, use `{{ webhookUrl }}` in the markdown snippet. </Tip>

DateTime

This property collects a date and time from the user.

Example:

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

Number

This property collects a numeric input from the user.

Example:

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

Static Dropdown

This property presents a dropdown menu with predefined options.

Example:

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

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

Static Multiple Dropdown

This property presents a dropdown menu with multiple selection options.

Example:

typescript
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.

Example:

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

Dictionary

This property collects key-value pairs from the user.

Example:

typescript
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.

Example:

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

Array of Strings

This property collects an array of strings from the user.

Example:

typescript
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.

Example:

typescript
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.

Example:

typescript
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',
        },
      ],
    };
  },
});
<Tip> When accessing the Piece auth, be sure to use exactly `auth` as it is hardcoded. However, for other properties, use their respective names. </Tip>

Multi-Select Dropdown

This property allows for multiple selections from dynamically loaded options.

Example:

typescript
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',
        },
      ],
    };
  },
});
<Tip> When accessing the Piece auth, be sure to use exactly `auth` as it is hardcoded. However, for other properties, use their respective names. </Tip>

Dynamic Properties

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

Example:

typescript

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;
  },
});

Custom Property (BETA)

<Warning> 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 </Warning> 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](/embedding/overview) 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 NameTypeDescription
onChange(value:unknown)=>voidA callback you call to set the value of your input (only call this inside event handlers)
valueunknownWhatever the type of the value you pass to onChange
containerIdstringThe ID of an HTML element in which you can modify the DOM however you like
isEmbeddedbooleanThe flag that tells you if the code is running inside an embedded instance of Activepieces
projectIdstringThe project ID of the flow the step that contains this property is in
disabledbooleanThe 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:

typescript
 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.