From dc892ac2324e45d7f6a76ceed2dc5ca19c8e05df Mon Sep 17 00:00:00 2001
From: Sage Abdullah <sage.abdullah@torchbox.com>
Date: Mon, 13 May 2024 15:58:03 +0100
Subject: [PATCH] Document UserViewSet customisation

---
 .../customisation/custom_user_models.md       | 46 +++++++++++++++++++
 docs/extending/customizing_group_views.md     |  2 +
 2 files changed, 48 insertions(+)

diff --git a/docs/advanced_topics/customisation/custom_user_models.md b/docs/advanced_topics/customisation/custom_user_models.md
index 3dcd65cd35..76fe06b758 100644
--- a/docs/advanced_topics/customisation/custom_user_models.md
+++ b/docs/advanced_topics/customisation/custom_user_models.md
@@ -81,3 +81,49 @@ WAGTAIL_USER_EDIT_FORM = 'users.forms.CustomUserEditForm'
 WAGTAIL_USER_CREATION_FORM = 'users.forms.CustomUserCreationForm'
 WAGTAIL_USER_CUSTOM_FIELDS = ['country', 'status']
 ```
+
+```{versionadded} 6.2
+The ability to customize the `UserViewSet` was added. Instead of customizing the forms via the `WAGTAIL_USER_EDIT_FORM`, `WAGTAIL_USER_CREATION_FORM`, and `WAGTAIL_USER_CUSTOM_FIELDS` settings, we recommend customizing them via the viewset instead, as explained below. The aforementioned settings might be deprecated in a future release.
+```
+
+(custom_userviewset)=
+
+## Custom `UserViewSet`
+
+Alternatively, you can also customize the forms and the views by creating a `UserViewSet` subclass. For example, with the above custom form classes, you can create the following `UserViewSet` subclass:
+
+```python
+from wagtail.users.views.users import UserViewSet as WagtailUserViewSet
+
+from .forms import CustomUserCreationForm, CustomUserEditForm
+
+
+class UserViewSet(WagtailUserViewSet):
+    def get_form_class(self, for_update=False):
+        if for_update:
+            return CustomUserEditForm
+        return CustomUserCreationForm
+```
+
+Then, configure the `wagtail.users` application to use the custom viewset, by setting up a custom `AppConfig` class. Within your project folder (which will be the package containing the top-level settings and urls modules), create `apps.py` (if it does not exist already) and add:
+
+```python
+from wagtail.users.apps import WagtailUsersAppConfig
+
+
+class CustomUsersAppConfig(WagtailUsersAppConfig):
+    user_viewset = "myapplication.someapp.viewsets.UserViewSet"
+```
+
+Replace `wagtail.users` in `settings.INSTALLED_APPS` with the path to `CustomUsersAppConfig`.
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "myapplication.apps.CustomUsersAppConfig",
+    # "wagtail.users",
+    ...,
+]
+```
+
+If you want to customize the group forms and views, see [](customizing_group_views).
diff --git a/docs/extending/customizing_group_views.md b/docs/extending/customizing_group_views.md
index 4b0a0f7e33..dcf9ea8d6e 100644
--- a/docs/extending/customizing_group_views.md
+++ b/docs/extending/customizing_group_views.md
@@ -107,6 +107,8 @@ INSTALLED_APPS = [
 ]
 ```
 
+If you want to customize the user forms and views instead, see [](custom_userviewset).
+
 (customizing_group_views_permissions_order)=
 
 ## Customizing the group editor permissions ordering