Overview
The Patch function is the primary method for creating new records and updating existing records in SharePoint lists from canvas apps. Understanding Patch syntax, how to reference columns by their internal names, and how to handle different column types is essential for building functional data entry forms and edit screens.
Prerequisites
- Power Apps canvas app experience
- Understanding of SharePoint lists and columns
- Familiarity with galleries and forms
- Basic knowledge of Power Apps formulas
What is the Patch Function?
In Power Apps canvas apps, the Patch function allows you to create new list items or update existing SharePoint list items without using the standard Edit Form control. Patch gives you precise control over which columns you're updating and when the update occurs, making it ideal for custom save buttons, bulk updates, or situations where you need more flexibility than forms provide.
Basic Patch syntax:
Patch(DataSource, BaseRecord, ChangeRecord)- DataSource – The SharePoint list you're updating (e.g., 'Project Tasks')
- BaseRecord – The existing record to update, or Defaults(DataSource) for new records
- ChangeRecord – A record containing the columns and values to update
Two common Patch patterns:
| Scenario | Pattern | Example |
|---|---|---|
| Create new record | Patch(List, Defaults(List), {Column: Value}) | Patch('Tasks', Defaults('Tasks'), {Title: "New task"}) |
| Update existing record | Patch(List, ThisItem, {Column: NewValue}) | Patch('Tasks', Gallery1.Selected, {Status: "Complete"}) |
When you Patch a SharePoint list, Power Apps immediately sends the changes to SharePoint and updates the local data source, so galleries and forms reflect the new data without needing to manually refresh.
How to Patch Different Column Types
Each SharePoint column type requires specific syntax in your Patch formula. Understanding these patterns is essential for successfully creating and updating records.
Common column types and their Patch syntax:
| Column Type | Patch Syntax |
|---|---|
| Single line of text | {Title: TextInput1.Text} |
| Multiple lines of text | {Description: TextInput2.Text} |
| Number | {Amount: Value(TextInput3.Text)} |
| Date only | {DueDate: DatePicker1.SelectedDate} |
| Date and Time | {Created: DatePicker1.SelectedDate} |
| Choice (dropdown) | {Status: Dropdown1.Selected.Value} |
| Yes/No | {IsActive: Toggle1.Value} |
| Person | {AssignedTo: {Claims: "i:0#.f|membership|user@domain.com"}} |
| Lookup | {Project: {Id: Dropdown2.Selected.ID}} |
| Hyperlink | {Website: "https://example.com"} |
Text and number columns:
Single line of text and multiple lines of text columns accept plain text strings. Number columns require the Value() function if you're pulling from a text input:
Patch(
'Tasks',
Defaults('Tasks'),
{
Title: TextInput_Title.Text,
Description: TextInput_Description.Text,
Amount: Value(TextInput_Amount.Text)
}
)Date columns:
Both Date and Date & Time columns accept the SelectedDate property from DatePicker controls:
Patch(
'Tasks',
Defaults('Tasks'),
{
DueDate: DatePicker_Due.SelectedDate,
StartDate: DatePicker_Start.SelectedDate
}
)Choice columns:
Choice columns (dropdowns) require the .Value property from the selected item:
Patch(
'Tasks',
Defaults('Tasks'),
{
Status: Dropdown_Status.Selected.Value,
Priority: Dropdown_Priority.Selected.Value
}
)Yes/No (Boolean) columns:
Toggle or Checkbox controls provide boolean values directly:
Patch(
'Tasks',
Defaults('Tasks'),
{
IsComplete: Toggle_Complete.Value,
IsUrgent: Checkbox_Urgent.Value
}
)Creating New SharePoint List Items
To create a new record, use Defaults(DataSource) as the BaseRecord parameter. This tells Power Apps you're creating a new item rather than updating an existing one.
Basic new record pattern:
Patch(
'Project Tasks',
Defaults('Project Tasks'),
{
Title: TextInput_Title.Text,
Description: TextInput_Description.Text,
Status: "Not Started"
}
)This creates a new item in the "Project Tasks" list with the Title and Description from text inputs, and Status set to "Not Started".
Complete example with multiple column types:
Patch(
'Expense Requests',
Defaults('Expense Requests'),
{
Title: TextInput_Description.Text,
Amount: Value(TextInput_Amount.Text),
Category: Dropdown_Category.Selected.Value,
SubmissionDate: DatePicker_Date.SelectedDate,
RequiresApproval: Toggle_Approval.Value,
Submitter: {
Claims: "i:0#.f|membership|" & User().Email
}
}
)This creates a complete expense request with text, number, choice, date, boolean, and person columns all set in a single Patch operation.
Setting the current user as Person column:
To set a Person column to the current logged-in user, use the User() function with the Claims property:
{
AssignedTo: {
Claims: "i:0#.f|membership|" & User().Email
}
}The "i:0#.f|membership|" prefix is required for SharePoint person columns. Concatenate it with the user's email address from User().Email.
Providing user feedback after creation:
// Button OnSelect
Set(varNewItem,
Patch(
'Tasks',
Defaults('Tasks'),
{
Title: TextInput_Title.Text,
Status: "New"
}
)
);
Notify("Task created successfully", NotificationType.Success);
Navigate(TaskDetailsScreen, ScreenTransition.None)This pattern stores the newly created item in a variable, shows a success notification, and navigates to a details screen. The variable varNewItem contains the complete record including the auto-generated ID, which you can use on the next screen.
Updating Existing SharePoint List Items
To update an existing record, reference the specific record as the BaseRecord parameter. Common sources include Gallery1.Selected (selected gallery item), LookUp results, or variables containing records.
Update from gallery selection:
Patch(
'Tasks',
Gallery_Tasks.Selected,
{
Status: "In Progress",
LastModified: Now()
}
)This updates the selected item in the gallery, changing its Status to "In Progress" and setting LastModified to the current timestamp.
Update from context variable:
If you stored a record in a variable (e.g., on screen navigation), update it directly:
// On previous screen, when navigating:
Navigate(EditScreen, ScreenTransition.None, {varCurrentTask: Gallery1.Selected})
// On EditScreen, update button:
Patch(
'Tasks',
varCurrentTask,
{
Title: TextInput_Title.Text,
Description: TextInput_Description.Text,
DueDate: DatePicker_Due.SelectedDate
}
)Update using LookUp:
If you know the ID or other unique identifier, use LookUp to find the record:
Patch(
'Tasks',
LookUp('Tasks', ID = varTaskID),
{
Status: "Completed",
CompletionDate: Today()
}
)Conditional updates:
Use If statements within Patch to conditionally set column values:
Patch(
'Tasks',
Gallery_Tasks.Selected,
{
Status: If(Toggle_Complete.Value, "Complete", "In Progress"),
Priority: If(Dropdown_Urgency.Selected.Value = "High", "Urgent", "Normal"),
CompletionDate: If(Toggle_Complete.Value, Now(), Blank())
}
)This sets different values based on control states—if the toggle is on, Status becomes "Complete" and CompletionDate is set to now. If the toggle is off, Status is "In Progress" and CompletionDate is cleared with Blank().
Patching Person and Lookup Columns
Person and Lookup columns require record references—you can't just pass a text string. You must provide the correct record structure with Claims (for Person) or Id (for Lookup).
Person column syntax:
Person columns in SharePoint store user information as claims-based records. To set a Person column in Patch:
// Set to current user
{
AssignedTo: {
Claims: "i:0#.f|membership|" & User().Email
}
}
// Set to specific user email
{
AssignedTo: {
Claims: "i:0#.f|membership|john.smith@powertech365.co.uk"
}
}
// Set from ComboBox selection (configured with People data source)
{
AssignedTo: {
Claims: ComboBox_Person.Selected.Claims
}
}Lookup column syntax:
Lookup columns reference another SharePoint list item by ID. To set a Lookup column:
// Set from Dropdown (Items property = Projects list)
{
Project: {
Id: Dropdown_Project.Selected.ID
}
}
// Set from variable containing a project record
{
Project: {
Id: varSelectedProject.ID
}
}
// Set using a specific ID value
{
Project: {
Id: 15
}
}The key is providing a record with an "Id" property (note the capital "I") that matches the ID of the item in the lookup list.
Complete example with Person and Lookup:
Patch(
'Tasks',
Defaults('Tasks'),
{
Title: TextInput_Title.Text,
Project: {
Id: Dropdown_Project.Selected.ID
},
AssignedTo: {
Claims: "i:0#.f|membership|" & ComboBox_User.Selected.Mail
},
DueDate: DatePicker_Due.SelectedDate
}
)This creates a new task with a lookup to a project (selected from dropdown) and a person column set to a user (selected from people picker ComboBox).
Clearing Person or Lookup columns:
To remove the value from a Person or Lookup column, set it to Blank():
Patch(
'Tasks',
Gallery_Tasks.Selected,
{
AssignedTo: Blank(),
Project: Blank()
}
)Complex Patch Scenarios
Beyond basic create and update operations, Patch supports advanced patterns for handling multiple records, conditional logic, and error handling.
Patching multiple columns conditionally:
Patch(
'Tasks',
Gallery_Tasks.Selected,
If(
Toggle_Complete.Value,
{
Status: "Complete",
CompletionDate: Now(),
CompletedBy: {
Claims: "i:0#.f|membership|" & User().Email
}
},
{
Status: "In Progress",
CompletionDate: Blank(),
CompletedBy: Blank()
}
)
)This uses If to return entirely different change records based on whether the toggle is on. If completing the task, it sets Status, CompletionDate, and CompletedBy. If uncompleting, it clears CompletionDate and CompletedBy.
Updating only changed values:
// Only patch if user changed the title
If(
TextInput_Title.Text <> Gallery_Tasks.Selected.Title,
Patch(
'Tasks',
Gallery_Tasks.Selected,
{Title: TextInput_Title.Text}
)
)Error handling with IfError:
IfError(
Patch(
'Tasks',
Defaults('Tasks'),
{
Title: TextInput_Title.Text,
Amount: Value(TextInput_Amount.Text)
}
),
Notify("Failed to create task: " & FirstError.Message, NotificationType.Error),
Notify("Task created successfully", NotificationType.Success)
)This wraps Patch in IfError to catch failures (e.g., required columns missing, invalid values) and show appropriate user feedback.
Patching after validation:
// Button OnSelect
If(
IsBlank(TextInput_Title.Text),
Notify("Title is required", NotificationType.Error),
IsBlank(DatePicker_Due.SelectedDate),
Notify("Due date is required", NotificationType.Error),
// All validation passed, perform patch
Patch(
'Tasks',
Defaults('Tasks'),
{
Title: TextInput_Title.Text,
DueDate: DatePicker_Due.SelectedDate,
Status: "New"
}
);
Notify("Task created", NotificationType.Success);
Navigate(TaskListScreen)
)Bulk updates using ForAll:
To patch multiple records at once, use ForAll to iterate through a collection:
// Mark all selected items as complete
ForAll(
Gallery_Tasks.AllItems,
If(
Checkbox_Select.Value,
Patch(
'Tasks',
ThisRecord,
{
Status: "Complete",
CompletionDate: Now()
}
)
)
)This loops through all gallery items, and for each item where the checkbox is checked, patches that record to mark it complete.
Next Steps
You now understand how to use Patch to create and update SharePoint list items from canvas apps, including working with different column types, person and lookup columns, and advanced patterns for validation and bulk updates.
Expand your Power Apps data manipulation skills by exploring:
- Remove function – Delete SharePoint list items from canvas apps with proper confirmation dialogs
- Collect and ClearCollect – Build temporary collections for complex data manipulation before patching to SharePoint
- Concurrent function – Perform multiple Patch operations simultaneously for better performance
- Delegation with Patch – Understanding which operations delegate and which process locally
- Attachments with Patch – Add or remove attachments from SharePoint list items programmatically
- Error handling patterns – Building robust error messages and retry logic for failed Patch operations
- Form vs Patch decision framework – When to use Edit Forms with SubmitForm vs custom interfaces with Patch
The Microsoft Power Fx reference for Patch provides comprehensive syntax documentation, examples, and guidance on advanced Patch scenarios including working with related tables and handling complex data structures.