0
# Prop Types
1

2
Comprehensive type system for component properties including user input props, validation schemas, and dynamic option loading.
3

4
## Capabilities
5

6
### Basic Prop Types
7

8
Core type definitions for basic property types.
9

10
```typescript { .api }
11
/**
12
 * Basic property types for user inputs
13
 */
14
type BasicPropType = 
15
  | "string"   // String input field
16
  | "boolean"  // Boolean checkbox
17
  | "integer"  // Numeric input field
18
  | "app";     // App reference
19

20
/**
21
 * Array variants of basic property types
22
 */
23
type ArrayPropType = 
24
  | "string[]"   // Array of strings
25
  | "boolean[]"  // Array of booleans
26
  | "integer[]"; // Array of integers
27

28
/**
29
 * App-specific property types for service integrations
30
 */
31
type AppSpecificPropType = 
32
  | "$.airtable.baseId"    // Airtable base selector
33
  | "$.airtable.tableId"   // Airtable table selector  
34
  | "$.airtable.viewId";   // Airtable view selector
35

36
/**
37
 * Union of all supported property types
38
 */
39
type PropType = BasicPropType | ArrayPropType | AppSpecificPropType;
40
```
41

42
### User Input Props
43

44
Main interface for configuring user input properties.
45

46
```typescript { .api }
47
/**
48
 * Configuration interface for user input properties
49
 */
50
interface UserInputProp {
51
  /** The type of property (required) */
52
  type: PropType;
53
  /** Display label for the property (optional) */
54
  label?: string;
55
  /** Help text describing the property (optional) */
56
  description?: string;
57
  /** Whether the property is optional (default: false) */
58
  optional?: boolean;
59
  /** Default value for the property (optional) */
60
  default?: any;
61
  /** Whether the property contains sensitive data (optional) */
62
  secret?: boolean;
63
  /** Minimum value for integer types (optional) */
64
  min?: number;
65
  /** Maximum value for integer types (optional) */
66
  max?: number;
67
  /** Available options for selection (optional) */
68
  options?: PropOptions;
69
  /** Enable search functionality for options (optional) */
70
  useQuery?: boolean;
71
  /** Reference to app prop definition (optional) */
72
  propDefinition?: [PipedreamApp, string, any?];
73
  /** Reference to app prop for app-specific types (optional) */
74
  appProp?: string;
75
  /** Reference to base ID prop for table/view selection (optional) */
76
  baseIdProp?: string;
77
  /** Reference to table ID prop for view selection (optional) */
78
  tableIdProp?: string;
79
}
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import { UserInputProp } from "@pipedream/types";
86

87
// Simple string input
88
const nameProperty: UserInputProp = {
89
  type: "string",
90
  label: "Name",
91
  description: "Enter your name",
92
  optional: false
93
};
94

95
// Integer with constraints
96
const ageProperty: UserInputProp = {
97
  type: "integer",
98
  label: "Age",
99
  description: "Your age in years",
100
  min: 0,
101
  max: 150,
102
  default: 25
103
};
104

105
// Secret field
106
const apiKeyProperty: UserInputProp = {
107
  type: "string",
108
  label: "API Key",
109
  description: "Your service API key",
110
  secret: true
111
};
112

113
// Property with static options
114
const statusProperty: UserInputProp = {
115
  type: "string",
116
  label: "Status",
117
  options: ["active", "inactive", "pending"]
118
};
119
```
120

121
### Prop Options
122

123
Type definitions for property option configurations.
124

125
```typescript { .api }
126
/**
127
 * Union type for property option configurations
128
 */
129
type PropOptions = 
130
  | string[]                              // Simple string array
131
  | { label: string; value: any }[]       // Label-value objects
132
  | AsyncOptionsMethod;                   // Dynamic options function
133

134
/**
135
 * Function interface for loading dynamic options
136
 */
137
interface AsyncOptionsMethod {
138
  (context: AsyncOptionsContext): Promise<
139
    | string[]
140
    | { label: string; value: any }[]
141
    | PaginatedOptionsResult
142
  >;
143
}
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
// Static string options
150
const simpleOptions: PropOptions = ["option1", "option2", "option3"];
151

152
// Label-value options
153
const labelValueOptions: PropOptions = [
154
  { label: "Development", value: "dev" },
155
  { label: "Production", value: "prod" },
156
  { label: "Staging", value: "stage" }
157
];
158

159
// Async options method
160
const asyncOptionsProperty: UserInputProp = {
161
  type: "string",
162
  label: "Select User",
163
  options: async ({ query, prevContext }) => {
164
    const users = await fetchUsers({ search: query });
165
    return users.map(user => ({
166
      label: user.name,
167
      value: user.id
168
    }));
169
  }
170
};
171
```
172

173
### Async Options Context
174

175
Context object passed to async options methods.
176

177
```typescript { .api }
178
/**
179
 * Context object passed to async options methods
180
 */
181
interface AsyncOptionsContext {
182
  /** Page number for numeric pagination (optional) */
183
  page?: number;
184
  /** Previous context token for pagination (optional) */
185
  prevContext?: string;
186
  /** Search query when useQuery is enabled (optional) */
187
  query?: string;
188
  /** Additional context from other component props */
189
  [key: string]: any;
190
}
191
```
192

193
### Paginated Options Result
194

195
Result object for paginated option loading.
196

197
```typescript { .api }
198
/**
199
 * Result object for paginated option loading
200
 */
201
interface PaginatedOptionsResult {
202
  /** Array of options (strings or label-value objects) */
203
  options: Array<string | { label: string; value: any }>;
204
  /** Context for next page (optional) */
205
  context?: {
206
    /** Token for loading the next page (optional) */
207
    nextPageToken?: string;
208
  };
209
}
210
```
211

212
**Usage Example:**
213

214
```typescript
215
const paginatedOptionsProperty: UserInputProp = {
216
  type: "string",
217
  label: "Select Repository",
218
  useQuery: true,
219
  options: async ({ query, prevContext }) => {
220
    const response = await fetchRepositories({
221
      search: query,
222
      pageToken: prevContext
223
    });
224
    
225
    return {
226
      options: response.repositories.map(repo => ({
227
        label: repo.fullName,
228
        value: repo.id
229
      })),
230
      context: response.nextPageToken ? {
231
        nextPageToken: response.nextPageToken
232
      } : undefined
233
    };
234
  }
235
};
236
```
237

238
### Prop Definition References
239

240
Reference system for reusing prop definitions from apps.
241

242
```typescript { .api }
243
/**
244
 * Reference to a prop definition from an app
245
 * Format: [AppReference, PropName, AdditionalParams?]
246
 */
247
type PropDefinitionReference = [PipedreamApp, string, any?];
248
```
249

250
**Usage Example:**
251

252
```typescript
253
// App with prop definitions
254
const githubApp: PipedreamApp = {
255
  type: "app",
256
  app: "github",
257
  propDefinitions: {
258
    repository: {
259
      type: "string",
260
      label: "Repository",
261
      description: "Select a GitHub repository",
262
      options: async ({ $auth }) => {
263
        const repos = await fetchUserRepos($auth.oauth_access_token);
264
        return repos.map(repo => ({
265
          label: repo.full_name,
266
          value: repo.full_name
267
        }));
268
      }
269
    }
270
  }
271
};
272

273
// Component using the prop definition
274
const componentUsingPropDef: PipedreamComponent = {
275
  name: "GitHub Component",
276
  version: "1.0.0",
277
  props: {
278
    github: githubApp,
279
    repo: {
280
      type: "string",
281
      propDefinition: [githubApp, "repository"]
282
    }
283
  },
284
  async run(event) {
285
    console.log("Selected repository:", this.repo);
286
  }
287
};
288
```
289

290
## Advanced Patterns
291

292
### Dynamic Property Dependencies
293

294
Properties that depend on values from other properties:
295

296
```typescript
297
const dependentProperty: UserInputProp = {
298
  type: "string",
299
  label: "Branch",
300
  description: "Select a branch from the repository",
301
  options: async ({ repo }) => {
302
    if (!repo) return [];
303
    const branches = await fetchBranches(repo);
304
    return branches.map(branch => branch.name);
305
  }
306
};
307
```
308

309
### Searchable Options
310

311
Properties with search functionality:
312

313
```typescript
314
const searchableProperty: UserInputProp = {
315
  type: "string",
316
  label: "Search Issues",
317
  description: "Search for GitHub issues",
318
  useQuery: true,
319
  options: async ({ query }) => {
320
    if (!query || query.length < 2) return [];
321
    const issues = await searchIssues(query);
322
    return issues.map(issue => ({
323
      label: `#${issue.number}: ${issue.title}`,
324
      value: issue.number
325
    }));
326
  }
327
};
328
```
329

330
### Array Properties
331

332
Properties that accept multiple values:
333

334
```typescript
335
const multiSelectProperty: UserInputProp = {
336
  type: "string[]",
337
  label: "Select Tags",
338
  description: "Choose multiple tags",
339
  options: ["bug", "feature", "enhancement", "documentation"]
340
};
341
```
342

343
### Conditional Properties
344

345
Properties that appear based on other property values:
346

347
```typescript
348
const conditionalProperty: UserInputProp = {
349
  type: "string",
350
  label: "Webhook URL",
351
  description: "URL for webhook notifications",
352
  optional: true,
353
  // Note: Conditional display logic is handled by Pipedream's runtime
354
  // This property would only be shown based on other property values
355
};
356
```
357

358
### App-Specific Properties
359

360
Properties that reference app-specific selectors and hierarchical selections:
361

362
```typescript
363
// Airtable base selector
364
const airtableBaseProperty: UserInputProp = {
365
  type: "$.airtable.baseId",
366
  appProp: "airtable" // References the airtable app prop
367
};
368

369
// Airtable table selector (depends on base)
370
const airtableTableProperty: UserInputProp = {
371
  type: "$.airtable.tableId",
372
  baseIdProp: "baseId" // References the baseId prop
373
};
374

375
// Airtable view selector (depends on table)
376
const airtableViewProperty: UserInputProp = {
377
  type: "$.airtable.viewId", 
378
  tableIdProp: "tableId" // References the tableId prop
379
};
380

381
// Complete component example with Airtable hierarchy
382
const airtableComponent: PipedreamComponent = {
383
  name: "Airtable Component",
384
  version: "1.0.0",
385
  props: {
386
    airtable: {
387
      type: "app",
388
      app: "airtable"
389
    } as PipedreamApp,
390
    baseId: {
391
      type: "$.airtable.baseId",
392
      appProp: "airtable"
393
    },
394
    tableId: {
395
      type: "$.airtable.tableId", 
396
      baseIdProp: "baseId"
397
    },
398
    viewId: {
399
      type: "$.airtable.viewId",
400
      tableIdProp: "tableId"
401
    }
402
  },
403
  async run(event) {
404
    console.log("Selected:", {
405
      base: this.baseId,
406
      table: this.tableId,
407
      view: this.viewId
408
    });
409
  }
410
};
411
```