diff --git a/pages/docs/features/custom-properties.mdx b/pages/docs/features/custom-properties.mdx
index 559c95f450..fba8b51721 100644
--- a/pages/docs/features/custom-properties.mdx
+++ b/pages/docs/features/custom-properties.mdx
@@ -10,7 +10,34 @@ import { Code, Callout } from 'nextra/components'
Custom properties lets you combine existing properties into new properties on the fly, using a simple Excel-like formula language. You can then use these new properties almost anywhere that you can use regular properties, with the ability to save/share them for reuse across your team. For more on why we built this, check out [our blog](https://mixpanel.com/blog/introducing-the-mixpanel-modeling-layer/).
-## Use Cases
+## Creating a Custom Property
+
+Click the plus button to the right of the search bar, then select either “Custom Event Property” or “Custom User Property” to open the property builder.
+
+
+
+Give your property a name
+
+
+
+Click the formula bar to start defining the calculations to perform for your property
+
+
+If you're new to this feature, we recommend starting with one of the examples. Click the **Insert Example** drop down to populate the box with a use-case specific custom property.
+
+When writing your formula, click **Ctrl + Space** to see a list of all the available functions and their descriptions. Click **period (.)** to search for event or user profile properties to add to the formula. If you are creating a “Custom Event Property” both event and user profile properties will be available to select. If you are creating a “Custom Profile Property” only user profile properties will be available for use in the custom property.
+
+Note that the formula used to compose your custom property can't be longer than 20,000 characters.
+
+
+
+## Saving and Reusing a Custom Property
+
+Custom properties are local to the report by default, when you select **Apply**. To save the custom property permanently for use in other reports and to make it usable by other project members, click **Save**. We recommend Applying the custom property and using it in your local analysis first, before saving and sharing, to reduce clutter in the project.
+
+When you create custom properties and select **Save as Custom Property**, your created custom property will be private by default. You can also add a description at this stage, so you and your colleagues can know what the custom property is for. You can also decide to save the custom property and **share** that custom property with specific colleagues, teams or the entire organization by clicking "**Save and Share**":
+
+## Common Use Cases
**Grouping Marketing Channels**
@@ -66,39 +93,68 @@ You can parse out the first delivery ID in a list property with several Delivery
The same syntax works with objects.
-**Borrow properties from one event onto subsequent events**
-
+## Borrowed Properties
-For events that cannot have certain properties easily tracked, borrowed properties comes into the picture. This functionality allows you to borrow the specific property from a preceding action
+Borrowed properties allow you to take a property from a prior event and automatically add it as a property on a future event without needing to explicitly track the property in the future event.
-
+### Use Cases:
+Use client-side properties to populate a property on a server-side event. Example: “purchase” event could be a server-side event, while the “product search” event is a client-side event.
+Track a single event property and apply it to subsequent events. Example: It may be hard to track whether every event has dark mode enabled. You would need to keep track of the state of dark mode, and then add a “darkmode” property to every event that you track. Using borrowed events, you can just track one event with a property that indicates whether dark mode has been enabled or not, and have subsequent events borrow the property from that event.
-Some scenarios where this functionality could be used:
-- **When merging events from 2 different systems, like server side & client side:**
- Use Case: You want to know transactions processed (which is a server side event), broken down by restaurant category (which is a property on a client side event order placed)
-- **When one team/ app wants to leverage tracking from 2+ teams/ apps:**
- Use Case: You want to know whether launch of Dark Mode, driven by the central team, impacted overall time spent on the page, which is your core KPI. Instead of adding the property - dark mode setting onto all the page view events, you can borrow this from existing tracking setup by the central launch team (dark mode toggle event)
-- **When wanting to join event properties within a product session**:
- Use Case: You want to know which in product banners led to most purchase conversions
+### Demo from ECommerce demo project
+Purchase Completed does not have “Search term”
+
-## Creating a Custom Property
+Products Searched does have “Search term”
+
-Click the plus button to the right of the search bar, then select Event Property or User Property to open the property builder.
+Create a custom event property
+
-
+Add a borrowed property
+
-Optionally give your property a name and click into the formula bar to start defining it. If you're new to this feature, we recommend starting with one of the examples. Click the **Insert Example** drop down to populate the box with a use-case specific custom property.
+Select event to borrow from
+
-When writing your formula, click **Ctrl + Space** to see a list of all the available functions and their descriptions. Click **period (.)** to search for event or user profile properties to add to the formula.
+Select the property to borrow
+
-
+### Borrowing mechanics
+Borrowed properties pick up the value from the most recent borrowed event.
+A seven day lookback window is applied, meaning the second event has to happen within seven days of the first event. If there is no first event within the lookback window, the value of the borrowed property will be (not set)
-Custom properties are local to the report by default, when you select **Apply**. To save the custom property permanently for use in other reports and to make it usable by other project members, click **Save**. We recommend Apply-ing the custom property and using it in your local analysis first, before saving and sharing, to reduce clutter in the project.
-When you create custom properties and select **Save as Custom Property**, your created custom property will be private by default. You can also add a description at this stage, so you and your colleagues can know what the custom property is for. You can also decide to save the custom property and **share** that custom property with specific colleagues, teams or the entire organization by clicking "**Save and Share**":
+How to create a borrowed property is demonstrated in this video
+
+
+
+
+
+Some key notes
+- Borrowed property creation is limited to Admin & Owner Roles only
+- A project can have a maximum of 20 borrowed properties. Hence you are encouraged to only create borrowed properties useful to the larger team
+- A borrowed property once created is like any other custom property. It can be accessed by all in the project depending on permissions
+- Borrowing of a property is strictly from the most recent event in the 7 day lookback window. To elaborate
+ - Say on event “purchase”, you want to borrow property “search term” from an event “search product”. If there are multiple events “search product” before “purchase”, the property will be borrowed from the most recent “search product” event where the property is set.
+ - Lookback is also fixed to a 7 day window. Say the “purchase” event occurred on 31st Jan, if the most recent “search product” occurred on 20th Jan, the borrow functionality will return “search term” = (not set), since this event happened 11 days ago which is outside the lookback window range.
+
+To use a borrowed property with other [functions](/docs/features/custom-properties#functions), you would need to:
+
+1. Create a custom property with just the borrowed property on it's own
+
+
+2. Create a separate custom property using the borrowed property (i.e. the 1st custom property)
+
+
+3. Here's an example of a [report](https://mixpanel.com/s/1c4Pl9) with *Searched Category* custom property using *Search term (Products Searched)* borrowed property
+
-Also note that the formula used to compose your custom property can't be longer than 20,000 characters.
## Reference
@@ -184,32 +240,3 @@ Use the following comparison operators in the **Formula** field to modify your c
- `true`: Represents the literal value of boolean true.
- `undefined`: Represents the literal value of cases that aren’t defined.
-### Borrowed Properties
-How to create a borrowed property is demonstrated in this video
-
-
-
-
-
-Some key notes
-- Borrowed property creation is limited to Admin & Owner Roles only
-- A project can have a maximum of 20 borrowed properties. Hence you are encouraged to only create borrowed properties useful to the larger team
-- A borrowed property once created is like any other custom property. It can be accessed by all in the project depending on permissions
-- Borrowing of a property is strictly from the most recent event in the 7 day lookback window. To elaborate
- - Say on event “purchase”, you want to borrow property “search term” from an event “search product”. If there are multiple events “search product” before “purchase”, the property will be borrowed from the most recent “search product” event where the property is set.
- - Lookback is also fixed to a 7 day window. Say the “purchase” event occurred on 31st Jan, if the most recent “search product” occurred on 20th Jan, the borrow functionality will return “search term” = (not set), since this event happened 11 days ago which is outside the lookback window range.
-
-To use a borrowed property with other [functions](/docs/features/custom-properties#functions), you would need to:
-
-1. Create a custom property with just the borrowed property on it's own
-
-
-2. Create a separate custom property using the borrowed property (i.e. the 1st custom property)
-
-
-3. Here's an example of a [report](https://mixpanel.com/s/1c4Pl9) with *Searched Category* custom property using *Search term (Products Searched)* borrowed property
-
diff --git a/public/1. Create Custom Event Property.png b/public/1. Create Custom Event Property.png
new file mode 100644
index 0000000000..fcf139c798
Binary files /dev/null and b/public/1. Create Custom Event Property.png differ
diff --git a/public/1. Create a Custom Property.png b/public/1. Create a Custom Property.png
new file mode 100644
index 0000000000..ae67cfd67e
Binary files /dev/null and b/public/1. Create a Custom Property.png differ
diff --git a/public/2. Add Borrowed Property.png b/public/2. Add Borrowed Property.png
new file mode 100644
index 0000000000..568615934a
Binary files /dev/null and b/public/2. Add Borrowed Property.png differ
diff --git a/public/2. Assign a name.png b/public/2. Assign a name.png
new file mode 100644
index 0000000000..9b3db11a6a
Binary files /dev/null and b/public/2. Assign a name.png differ
diff --git a/public/3. Select Products Searched.png b/public/3. Select Products Searched.png
new file mode 100644
index 0000000000..2e5220af1c
Binary files /dev/null and b/public/3. Select Products Searched.png differ
diff --git a/public/4. Select Search Terms.png b/public/4. Select Search Terms.png
new file mode 100644
index 0000000000..0868dc8aa8
Binary files /dev/null and b/public/4. Select Search Terms.png differ
diff --git a/public/Products Searched.png b/public/Products Searched.png
new file mode 100644
index 0000000000..1b71968b01
Binary files /dev/null and b/public/Products Searched.png differ
diff --git a/public/Purchase Completed.png b/public/Purchase Completed.png
new file mode 100644
index 0000000000..e940260e1b
Binary files /dev/null and b/public/Purchase Completed.png differ