Property Types

What are Properties?

Properties are inputs that users configure for actions and triggers. They define what information is needed to execute your piece’s functionality.

Activepieces provides rich property types for different kinds of input:

Text

ShortText, LongText

Number

Numeric input

Boolean

Checkbox

Selection

Dropdown, Multi-select

Date & Time

DateTime picker

Files

File uploads

Structured Data

JSON, Object, Array

Dynamic

Dynamic properties

Text Properties

ShortText

Single-line text input for names, IDs, URLs, etc.

Property.ShortText({
  displayName: 'Channel ID',
  description: 'The Slack channel ID',
  required: true,
  defaultValue: 'general',
})

displayName

string

required

Label shown to users

description

string

Helper text explaining what to enter

required

boolean

default:"false"

Whether the field is required

defaultValue

string

Pre-filled default value

LongText

Multi-line text input for messages, descriptions, etc.

Property.LongText({
  displayName: 'Message',
  description: 'The message content',
  required: true,
})

Number Property

Numeric input with optional min/max validation.

Property.Number({
  displayName: 'Max Results',
  description: 'Maximum number of results to return',
  required: false,
  defaultValue: 10,
  validators: [
    {
      type: 'number',
      min: 1,
      max: 100,
    },
  ],
})

validators

Validator[]

Validation rules for min/max values

validators: [{
  type: 'number',
  min: 1,
  max: 100,
}]

Checkbox Property

Boolean input for yes/no options.

Property.Checkbox({
  displayName: 'Include Metadata',
  description: 'Include additional metadata in response',
  required: true,
  defaultValue: false,
})

Predefined list of options.

Property.StaticDropdown({
  displayName: 'Priority',
  description: 'Issue priority level',
  required: true,
  options: {
    options: [
      { label: 'Low', value: 'low' },
      { label: 'Medium', value: 'medium' },
      { label: 'High', value: 'high' },
      { label: 'Critical', value: 'critical' },
    ],
  },
  defaultValue: 'medium',
})

Options loaded from API at runtime.

Property.Dropdown({
  displayName: 'Repository',
  description: 'Select a repository',
  required: true,
  refreshers: [], // Refresh when these properties change
  
  // Function to fetch options
  options: async ({ auth }) => {
    const response = await fetch('https://api.github.com/user/repos', {
      headers: {
        'Authorization': `Bearer ${auth.access_token}`,
      },
    });
    
    const repos = await response.json();
    
    return {
      options: repos.map((repo) => ({
        label: repo.full_name,
        value: repo.id,
      })),
    };
  },
})

refreshers

string[]

Property names that trigger a refresh when changed

// Refresh channels when workspace changes
refreshers: ['workspace']

refreshOnSearch

boolean

Re-fetch options when user types in search

Allow selecting multiple options.

Property.StaticMultiSelectDropdown({
  displayName: 'Labels',
  description: 'Select one or more labels',
  required: false,
  options: {
    options: [
      { label: 'Bug', value: 'bug' },
      { label: 'Feature', value: 'feature' },
      { label: 'Documentation', value: 'docs' },
    ],
  },
})

DateTime Property

Date and time picker.

Property.DateTime({
  displayName: 'Due Date',
  description: 'When the task is due',
  required: false,
})

Returns ISO 8601 format: 2024-01-15T10:30:00Z

File Property

File upload input.

Property.File({
  displayName: 'Attachment',
  description: 'File to upload',
  required: false,
})

Returns file object:

{
  filename: 'document.pdf',
  extension: 'pdf',
  data: Buffer,
  base64: 'base64string...',
}

JSON Property

JSON input with validation.

Property.Json({
  displayName: 'Metadata',
  description: 'Additional metadata as JSON',
  required: false,
  defaultValue: {
    key: 'value',
  },
})

Object Property

Key-value pairs.

Property.Object({
  displayName: 'Headers',
  description: 'HTTP headers as key-value pairs',
  required: false,
})

Returns:

{
  'Content-Type': 'application/json',
  'Authorization': 'Bearer token',
}

Array Property

Array of values with specified type.

Property.Array({
  displayName: 'Tags',
  description: 'List of tags',
  required: false,
  properties: {
    tag: Property.ShortText({
      displayName: 'Tag',
      required: true,
    }),
  },
})

Dynamic Properties

Properties that change based on other property values.

Property.DynamicProperties({
  displayName: 'Event Fields',
  description: 'Fields for the selected event',
  required: true,
  refreshers: ['eventType'], // Refresh when eventType changes
  
  props: async ({ auth, eventType }) => {
    if (!eventType) {
      return {};
    }
    
    // Fetch field definitions for selected event type
    const response = await fetch(
      `https://api.example.com/events/${eventType}/fields`,
      {
        headers: {
          'Authorization': `Bearer ${auth.access_token}`,
        },
      }
    );
    
    const fields = await response.json();
    
    // Build properties dynamically
    const properties = {};
    
    for (const field of fields) {
      properties[field.name] = Property.ShortText({
        displayName: field.label,
        description: field.description,
        required: field.required,
      });
    }
    
    return properties;
  },
})

Markdown Property

Display formatted text (not an input).

Property.MarkDown({
  value: `
### Setup Instructions

1. Go to your account settings
2. Navigate to API section
3. Generate a new API key
4. Copy the key and paste it above
  `,
})

Custom Property

Build completely custom UI components.

Property.Custom({
  displayName: 'Custom Input',
  required: true,
  code: `
    export function main(props) {
      // Custom React component
      return (
        <div>
          <input 
            type="text" 
            value={props.value}
            onChange={(e) => props.onChange(e.target.value)}
          />
        </div>
      );
    }
  `,
})

Property Validation

Add validation to ensure correct input:

Number Validation
Text Pattern
Custom Validation

Property.Number({
  displayName: 'Quantity',
  required: true,
  validators: [
    {
      type: 'number',
      min: 1,
      max: 1000,
    },
  ],
})

Property.ShortText({
  displayName: 'Email',
  required: true,
  validators: [
    {
      type: 'string',
      pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
    },
  ],
})

// Validate in action run function
async run(context) {
  const email = context.propsValue.email;
  
  if (!email.includes('@')) {
    throw new Error('Invalid email address');
  }
  
  // Continue with logic
}

Real-World Examples

Slack Channel Selector

Property.Dropdown({
  displayName: 'Channel',
  description: 'Select a Slack channel',
  required: true,
  refreshers: [],
  options: async ({ auth }) => {
    const response = await fetch(
      'https://slack.com/api/conversations.list',
      {
        headers: {
          'Authorization': `Bearer ${auth.access_token}`,
        },
      }
    );
    
    const data = await response.json();
    
    return {
      options: data.channels
        .filter(ch => !ch.is_archived)
        .map(ch => ({
          label: `#${ch.name}`,
          value: ch.id,
        })),
    };
  },
})

GitHub Repository with Dynamic Fields

props: {
  repository: Property.Dropdown({
    displayName: 'Repository',
    required: true,
    refreshers: [],
    options: async ({ auth }) => {
      const repos = await fetchRepos(auth);
      return {
        options: repos.map(r => ({
          label: r.full_name,
          value: r.id,
        })),
      };
    },
  }),
  
  issueFields: Property.DynamicProperties({
    displayName: 'Issue Fields',
    required: true,
    refreshers: ['repository'],
    props: async ({ auth, repository }) => {
      if (!repository) return {};
      
      // Get custom fields for this repository
      const fields = await fetchCustomFields(auth, repository);
      
      const props = {};
      for (const field of fields) {
        props[field.key] = Property.ShortText({
          displayName: field.name,
          required: field.required,
        });
      }
      
      return props;
    },
  }),
}

File Upload with Metadata

props: {
  file: Property.File({
    displayName: 'File',
    description: 'File to upload',
    required: true,
  }),
  
  visibility: Property.StaticDropdown({
    displayName: 'Visibility',
    required: true,
    options: {
      options: [
        { label: 'Private', value: 'private' },
        { label: 'Team', value: 'team' },
        { label: 'Public', value: 'public' },
      ],
    },
    defaultValue: 'private',
  }),
  
  tags: Property.Array({
    displayName: 'Tags',
    required: false,
    properties: {
      tag: Property.ShortText({
        displayName: 'Tag',
        required: true,
      }),
    },
  }),
  
  metadata: Property.Json({
    displayName: 'Custom Metadata',
    required: false,
    defaultValue: {},
  }),
}

Best Practices

Use Appropriate Property Types

Choose the right property type for the data:

Email/URL: ShortText with validation
Description: LongText
Selection from list: Dropdown
Multiple selections: MultiSelectDropdown
Yes/No: Checkbox
Structured data: JSON or Object

Provide Clear Descriptions

Help users understand what to enter:

Property.ShortText({
  displayName: 'API Key',
  description: 'Find your API key at https://example.com/settings/api',
  required: true,
})

Set Sensible Defaults

Pre-fill common values:

Property.Number({
  displayName: 'Timeout (seconds)',
  defaultValue: 30,
  required: false,
})

Use Refreshers for Dependencies

Refresh dependent dropdowns:

Property.Dropdown({
  displayName: 'Database',
  refreshers: ['connection'], // Refresh when connection changes
  options: async ({ connection }) => {
    // Fetch databases for selected connection
  },
})

Validate Critical Inputs

Add validation for important fields:

Property.Number({
  displayName: 'Port',
  validators: [{
    type: 'number',
    min: 1,
    max: 65535,
  }],
})

Getting Started

Development

Publishing

Property Types

What are Properties?

Property Types

Text

Number

Boolean

Selection

Date & Time

Files

Structured Data

Dynamic

Text Properties

ShortText

LongText

Number Property

Checkbox Property

DateTime Property

File Property

JSON Property

Object Property

Array Property

Dynamic Properties

Markdown Property

Custom Property

Property Validation

Real-World Examples

Best Practices

Next Steps

Create Actions

Testing

Getting Started

Development

Publishing

​What are Properties?

​Property Types

Text

Number

Boolean

Selection

Date & Time

Files

Structured Data

Dynamic

​Text Properties

​ShortText

​LongText

​Number Property

​Checkbox Property

​Dropdown Properties

​Static Dropdown

​Dynamic Dropdown

​Multi-Select Dropdown

​DateTime Property

​File Property

​JSON Property

​Object Property

​Array Property

​Dynamic Properties

​Markdown Property

​Custom Property

​Property Validation

​Real-World Examples

​Best Practices

​Next Steps

Create Actions

Testing

What are Properties?

Property Types

Text Properties

ShortText

LongText

Number Property

Checkbox Property

Dropdown Properties

Static Dropdown

Dynamic Dropdown

Multi-Select Dropdown

DateTime Property

File Property

JSON Property

Object Property

Array Property

Dynamic Properties

Markdown Property

Custom Property

Property Validation

Real-World Examples

Best Practices

Next Steps