diff --git a/client/docs/composables.md b/client/docs/composables.md
new file mode 100644
index 00000000000..2ba75d898fc
--- /dev/null
+++ b/client/docs/composables.md
@@ -0,0 +1,107 @@
+# Composables
+
+Composables are way of splitting up your code into distinct, reusable chunks.
+They can replace providers, mixins and more. Any code you can put into a component, can also be written as a composable.
+Using them effectively can make your code more reusable, decoupled, and easier to follow.
+
+**More about Composables:**
+
+* [Composables Overview](https://vuejs.org/guide/reusability/composables.html)
+* [Composition API](https://vuejs.org/api/composition-api-setup.html)
+* [\
+```
+
+You can now access the current user with `currentUser.value`.
+
+## Using Composables in the Options API
+
+Composables are not limited to the composition api. This is the same example from above, using the options api.
+
+```vue
+
+```
+
+You can now access the current user with `this.currentUser` from anywhere within the component.
+
+## Testing Components with Composable Stores
+
+When writing a test which includes a component that has a composable store (like useCurrentUser),
+there are two ways to test it.
+
+### Mocking the store
+
+You can provide the store in the mount function as follows:
+
+```js
+const wrapper = shallowMount(TestedComponent,
+ localVue,
+ provide: { store },
+});
+```
+
+`store` must be a Vuex store.
+The `mockModule` helper can help creating a store for the required modules:
+
+```js
+const store = new Vuex.Store({
+ modules: {
+ user: mockModule(userStore),
+ },
+});
+```
+
+### Mocking the composable
+
+The second option is to mock the composable:
+
+```js
+import { useCurrentUser } from "composables/user";
+
+jest.mock("composables/user");
+useCurrentUser.mockReturnValue({
+ currentUser: {}
+});
+```
+
+While simpler in this example, you may need to manually mock more return values and composables than the other method, depending on the composables the component is using.
+
+## Using Composables for more than Stores
+
+Composables can be of great use to extract any reactive code from your components. For an example of this, take a look at [userFilterObjectArray](https://github.com/galaxyproject/galaxy/blob/dev/client/src/composables/utils/filter.js).
+
+Usage:
+
+```vue
+
+```
+
+It's a simple filtering function, but fully reactive.
+Whenever any of the inputs changes, the return value is re-computed, without having to call the function again.
diff --git a/client/docs/providers-and-renderers.md b/client/docs/providers-and-renderers.md
index 447e6d74b74..480bef218ef 100644
--- a/client/docs/providers-and-renderers.md
+++ b/client/docs/providers-and-renderers.md
@@ -1,3 +1,7 @@
+**Notice** Consider using [Composables](composables.md) instead of Providers. They offer more functionality and need less boilerplate.
+
+---
+
We are using components in two very distinct ways. The first, "normal", kind of component will
probably look familiar to anybody whis is already passingly familiar with Vue. Here the relevant
information comes in as properties, any internal variables get defined in "data", changes go out as
@@ -27,7 +31,7 @@ restriction that Vue needs a single root element in which to render.
@@ -35,7 +39,7 @@ restriction that Vue needs a single root element in which to render.