Widget UserPicker

The UserPicker widget provides a searchable dropdown interface for selecting one or multiple users from your application's user base. It supports remote search, group filtering, and flexible display options.

Overview#Direct link to Overview

The UserPicker widget renders as an Element UI select component with remote search capabilities. Users can search and select from the application's user directory with real-time filtering and group-based restrictions.

Configuration Properties#Direct link to Configuration Properties

Basic Properties#Direct link to Basic Properties

Name#Direct link to Name

• Description: Display label for the widget
• Type: String
• Default: "Select a user"
• Usage: Appears as the form label above the selection field

Variable/Model#Direct link to Variable/Model

• Description: The data model variable name that will store the selected user(s)
• Type: String
• Required: Yes
• Format: Must be a valid variable name (e.g., selectedUser, assignedUsers)

Selection Options#Direct link to Selection Options

Multiple Selection#Direct link to Multiple Selection

• Property: multiple
• Type: Boolean
• Default: false
• Description: Enable selection of multiple users
• When enabled: Returns an array of selected user emails
• When disabled: Returns a single user email string

Clearable#Direct link to Clearable

• Property: clearable
• Type: Boolean
• Default: false
• Description: Adds a clear button to remove all selections

User Filtering#Direct link to User Filtering

Groups Filter#Direct link to Groups Filter

• Property: groupes
• Type: Array of Group Objects
• Description: Restrict user selection to specific groups
• Configuration: Select one or more groups from the dropdown
• API Behavior: Only users belonging to the selected groups will appear in search results

Label Display#Direct link to Label Display

• Property: label
• Type: String
• Options:
  • "name": Display user's first name + last name
  • "Email": Display user's email address
• Default: "Email"
• Description: Determines how users are displayed in the dropdown options

Validation and Visibility#Direct link to Validation and Visibility

Screen-Based Configuration#Direct link to Screen-Based Configuration

The title widget supports different configurations for different screens/contexts:

• Available: Controls widget visibility on the interface
• Visible: Controls widget visibility on the interface
• Required: Makes user selection mandatory for form submission
• Disable: Disables the widget preventing user interaction

Advanced Visibility Conditions#Direct link to Advanced Visibility Conditions

Use JavaScript expressions for complex visibility logic:

Style and Appearance#Direct link to Style and Appearance

Placeholder Text#Direct link to Placeholder Text

• Property: placeholder
• Type: String
• Default: "Search for a user..."
• Description: Placeholder text displayed when no selection is made

Width#Direct link to Width

• Property: width
• Type: String
• Default: "100%"
• Examples: "300px", "50%", "auto"
• Description: Controls the width of the selection field

CSS Classes#Direct link to CSS Classes

• Property: classNames
• Type: String
• Description: Custom CSS classes for styling
• Format: Space-separated class names

Dynamic Classes#Direct link to Dynamic Classes

• Property: classes
• Type: JavaScript Object
• Description: Conditional CSS classes based on form state
• Usage: Advanced styling based on data conditions

Validation Rules#Direct link to Validation Rules

Add custom validation rules beyond basic required validation:

Rule Types#Direct link to Rule Types

• Pattern: Regular expression validation
• Custom: JavaScript function validation
• Length: Minimum/maximum selection count (for multiple selection)

Usage Examples#Direct link to Usage Examples

Basic Single User Selection#Direct link to Basic Single User Selection

Multiple User Selection with Group Filter#Direct link to Multiple User Selection with Group Filter

Events and Interactions#Direct link to Events and Interactions

onChange Event#Direct link to onChange Event

• Trigger: When user selection changes
• Data Available:
  • SF_input.value: Selected user email(s)
  • SF_input.SF_data: Complete user object(s)
  • SF_input.SF_currentIndex: Current loop index (if in a loop)

Data Structure#Direct link to Data Structure

Input Data (Selected Values)#Direct link to Input Data (Selected Values)

// Single selection
"user@example.com"[
  // Multiple selection
  ("user1@example.com", "user2@example.com", "user3@example.com")
];

Complete User Objects (Available in SF_data)#Direct link to Complete User Objects (Available in SF_data)

{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "_id": "user_id_123",
  // Additional user properties
}

API Integration#Direct link to API Integration

User Search Endpoint#Direct link to User Search Endpoint

• URL: /api/v1/user
• Method: GET
• Parameters:
  • limit: Maximum results (default: 10)
  • groups: Comma-separated group IDs for filtering
  • key: Search query string
  • SF_mode: Application mode parameter

Group Filtering#Direct link to Group Filtering

When groups are configured, the API request automatically includes group filters to restrict results to users belonging to the specified groups.

Best Practices#Direct link to Best Practices

Performance Optimization#Direct link to Performance Optimization

• Use group filtering to reduce search result size
• Set appropriate search limits for large user bases
• Consider caching frequently accessed user data

User Experience#Direct link to User Experience

• Provide clear placeholder text indicating the selection purpose
• Use descriptive labels that match your use case
• Enable clearable option for better user control
• Choose appropriate label format (name vs email) based on context

Validation Strategy#Direct link to Validation Strategy

• Use required validation for critical selections
• Implement conditional validation based on form context
• Provide meaningful error messages for validation failures

Accessibility#Direct link to Accessibility

• Ensure proper labeling for screen readers
• Maintain keyboard navigation support
• Use semantic HTML through Element UI components

Troubleshooting#Direct link to Troubleshooting

Common Issues#Direct link to Common Issues

No Users Appearing#Direct link to No Users Appearing

• Check group filter configuration
• Verify user API endpoint availability
• Ensure users exist in the specified groups

Selection Not Saving#Direct link to Selection Not Saving

• Verify model/variable name is correctly configured
• Check for form validation errors
• Ensure proper data binding in parent form

Performance Issues#Direct link to Performance Issues

• Reduce group scope if too many users
• Implement pagination for large datasets
• Optimize search query parameters