reference field-custom-filter-api (PR from TinaCMS)

content/docs/reference/types/reference.mdx

@@ -1,6 +1,6 @@
 ---
 title: The "reference" field
-last_edited: '2024-09-12T01:50:26.823Z'
+last_edited: '2024-10-03T00:46:00.053Z'
 next: ''
 previous: ''
 ---
@@ -141,6 +141,69 @@ You can search your reference with reference selector.
     }
 ```
 
+### Filter reference
+
+If you have a long list of reference items, you can filter them in the schema using the `ui.collectionFilter` field with any property you defined in the referenced collection.
+
+> Note: Current `collectionFilter`only support property of type string and **case sensitive.** ( e.g. Using the example below, If you enter `australia` it will not work)).
+
+> Senario: You have a list of author in different location, and you only want the reference select in your post collection to show the desired location.
+
+```typescript
+const referenceField = {
+  label: 'Author',
+  name: 'author',
+  type: 'reference',
+  ui: {
+    collectionFilter: {
+      author: {
+        location: 'Australia'
+      }
+    },
+  },
+  collections: ['author'],
+}
+```
+
+It's also possible to filter references options based on a list of values.
+
+```typescript
+const referenceField = {
+  label: 'Author',
+  name: 'author',
+  type: 'reference',
+  ui: {
+    collectionFilter: {
+      author: {
+        location: ['Australia','United States']
+      }
+    },
+  },
+  collections: ['author'],
+}
+```
+
+Reference fields on multiple collections can be filtered by the values in either collection.
+
+```typescript
+const referenceField = {
+  label: 'Author & Post',
+  name: 'author and post',
+  type: 'reference',
+  ui: {
+    collectionFilter: {
+      author: {
+        location: ['Australia','United States']
+      },
+    post: {
+        status: 'published',
+      },
+    },
+  },
+  collections: ['author', 'post'],
+}
+```
+
 ### Customizing Reference Selector with optionComponent
 
 The default reference selector displays the file path, there are cases where you may want to customize what is displayed in the dropdown to provide a better user experience. For example, showing the author's name instead of the file name can make the selection process more intuitive.