From 295473f9242399b64b20c8d04a97f48b3f50bd5a Mon Sep 17 00:00:00 2001
From: David Kurek <david.kurek@hotmail.de>
Date: Thu, 13 Apr 2023 12:13:42 +0200
Subject: [PATCH] docs: add a brief description of `transform`/`pick` (#20186)

---
 docs/1.getting-started/6.data-fetching.md | 51 +++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/1.getting-started/6.data-fetching.md b/docs/1.getting-started/6.data-fetching.md
index f001320633..7800cb16d3 100644
--- a/docs/1.getting-started/6.data-fetching.md
+++ b/docs/1.getting-started/6.data-fetching.md
@@ -127,6 +127,57 @@ watch(count, (newCount) => {
 </script>
 ```
 
+## Transforming Data
+
+If for some reason you are not satisfied with how the requested data is structured, you may want to use the `transform` option from `useFetch` or `useAsyncData` to alter the data by using a function to perform the necessary transformation after your request has been resolved.
+
+We very much recommend that you remove any data or properties that you do not need, in order to reduce your page's payload size - see the [Minimize Payload](#minimize-payload) section.
+
+### Example
+
+```vue
+<script setup>
+const { data: users } = await useAsyncData(
+  "users",
+  () => $fetch('/api/users'),
+  {
+    transform: (users) =>
+      users.map((user) => ({
+        id: user.id,
+        fullName: `${user.firstName} ${user.surname}`,
+      })),
+  }
+);
+</script>
+
+<template>
+  <div>
+    <ul>
+      <li v-for="user in users" :key="user.id">
+        {{ user.fullName }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+If you are dealing with a complex data structure and you are only interested in a few properties, simply make use of the `pick` option to only pick specific properties you are interested in.
+
+```vue
+<script setup>
+const { data: user } = await useFetch('/api/users/123', {
+  pick: ["firstName", "surname"],
+});
+const userFullName = computed(
+  () => `${user.value.firstName} ${user.value.surname}`
+);
+</script>
+
+<template>
+  <div>Hi {{ userFullName }}</div>
+</template>
+```
+
 ## Refreshing Data
 
 Sometimes throughout the course of your user's page visit, you may need to refresh the data loaded from the API. This can happen if the user chooses to paginate, filter results, search, etc.