Composables
There are several Vue composables available as part of the Directus Extensions SDK that make working with Directus easier when building app extensions.
Rather than needing to rewrite logic from scratch, extension developers can leverage primitives like useApi() or useStores(), to handle common complexities when building extensions.
useApi()
The useApi composable is a wrapper around the axios library that uses the Data Studio's session cookie and provides concurrency
control when making multiple requests. Use the useApi composable when you need to make authorized API requests from your app extension.
<script setup>
import { useApi } from '@directus/extensions-sdk';
const api = useApi();
async function fetchData() {
const response = await api.get('ENDPOINT_URL');
data.value = response.data;
};
</script>
useStores()
The useStores composable serves as the primary way for app extensions to interact with data and features within a Directus project. useStores contains all stores, including usePermissionsStore, useCollectionsStore, and useFieldsStore.
<script setup>
import { useStores } from '@directus/extensions-sdk';
const { useFieldsStore, usePermissionsStore, useCollectionStore } = useStores();
const fieldsStore = useFieldsStore();
const permissionsStore = usePermissionsStore();
const collectionStore = useCollectionStore();
</script>
useFieldsStore()
The useFieldsStore is used to access and modify collections and fields. Use this store to retrieve field information, perform field mutations, or get field translations.
<script setup>
import { useStores } from '@directus/extensions-sdk';
const { useFieldsStore } = useStores();
const fieldsStore = useFieldsStore();
// create a field
const newField = await fieldStore.createField('collection_key', {
name: 'title',
});
// update a field
const updatedField = await fieldStore.updateField(
'collection_key',
'field_key',
{
name: 'new title',
}
);
</script>
usePermissionsStore()
The usePermissionsStore is used to check the current user's access control before performing operations within your app extension.
<script setup>
import { useStores } from '@directus/extensions-sdk';
const { usePermissionsStore } = useStores();
const permissionsStore = usePermissionsStore();
// check if user can create a collection
const canCreate = permissionsStore.hasPermission('collection_name', 'create');
// check if user can read a collection
const canRead = permissionsStore.hasPermission('collection_name', 'read');
</script>
useCollectionsStore()
The useCollectionsStore provides access to collections directly from your App extension. Use this store for CRUD operations on collections, retrieving translations, and accessing all or visible collections in Directus.
<script setup>
import { useStores } from '@directus/extensions-sdk';
const { useCollectionsStore } = useStores();
const collectionsStore = useCollectionsStore();
// get all collections
collectionsStore.collections.value;
// get all visible collections
collectionsStore.visibleCollections.value;
// get a collection
collectionStore.getCollection('collection_key');
// delete a collection
await collectionStore.deleteCollection('collection_key');
// upsert (create or update) a collection
await collectionStore.upsertCollection('collection_key', {...});
</script>
useCollection()
The useCollection composable provides access to metadata about collections. Use this store to retrieve collection metadata, fields, default values, primary key, and accountability scope. You can't use it to manipulate collection configuration.
<script setup>
import { useCollection } from '@directus/extensions-sdk';
const { info, fields, defaults, primaryKeyField } = useCollection('collection_name');
info.value;
// => [{ name: 'collection_name', icon: 'box', type: 'table', ... }]
fields.value;
// => [{ name: 'title', type: 'string', ... }]
defaults.value;
// => { title: 'default_value' }
primaryKeyField.value;
// => { name: 'id', type: 'uuid', ... }
</script>
useItems()
The useItems composable is used to retrieve items in a collection and provides pagination features.
Fetching Items in a Collection
<script setup>
import { useItems } from '@directus/extensions-sdk';
const collectionRef = ref('collection_key');
const query = {
fields: ref(['*']),
limit: ref(1),
sort: ref(null),
search: ref(null),
filter: ref(null),
page: ref(1),
}
const { getItems, items } = useItems(collectionRef, query);
query.search.value = 'search_value' // update query search
query.limit.value = 10 // update query limit
await getItems(); // fetch the items
const data = items.value; // read the items
</script>
Fetching the Item and Page Count
<script setup>
import { useItems } from '@directus/extensions-sdk';
const collectionRef = ref('collection_key')
const { getItemCount, itemCount, totalPages } = useItems(collectionRef);
await getItemCount(); // fetch the item count
const data = itemCount.value; // read the item count
const pages = totalPages.value; // read the total pages
</script>
Fetching the Total Count
<script setup>
import { useItems } from '@directus/extensions-sdk';
const collectionRef = ref('collection_key')
const { getTotalCount, totalCount } = useItems(collectionRef);
await getTotalCount(); // fetch the total item count
const data = totalCount.value; // read the total item count
</script>
Next Steps
While these core composables cover many common use cases, for a complete reference of all available Extension SDK composables within Directus, check out our source code. Our source code also contains the full list in of stores.