Composables

Complete API reference for all composables provided by nuxt-directus-sdk.

TypeScript Support

All composables are fully typed with TypeScript:

// User is typed as DirectusUser
const { user } = useDirectusAuth()
user.value?.email // string | undefined
user.value?.first_name // string | undefined

// Directus client is typed with your schema
const directus = useDirectus()
const articles = await directus.request(readItems('articles'))
// articles is typed based on your Directus schema

// File options are typed
const url = getDirectusFileUrl(file, {
  fit: 'cover', // Only allows: 'cover' | 'contain' | 'inside' | 'outside'
  format: 'webp', // Only allows: 'jpg' | 'png' | 'webp' | 'tiff' | 'avif'
})

Auto-Imported Directus SDK Functions

The module auto-imports every function exported by @directus/sdk — including any new ones added in future SDK releases — so you can call them directly without an import statement. The module reads the SDK's exports at build time, so whichever version of @directus/sdk you have installed, those functions are what you get.

Usage:

const directus = useDirectus()

const articles = await directus.request(readItems('articles', {
  filter: { status: { _eq: 'published' } },
  fields: ['*', { author: ['*'] }],
  sort: ['-date_created'],
  limit: 10,
}))

const article = await directus.request(readItem('articles', 'id', {
  fields: ['*', { author: ['first_name', 'last_name'] }],
}))

const created = await directus.request(createItem('articles', {
  title: 'New Article',
  status: 'draft',
}))

Functions Excluded from Auto-Import

A small number of SDK functions are intentionally not auto-imported — either because this module provides a composable wrapper, or because the function is an internal SDK detail. All of them can still be imported manually from @directus/sdk when you have a specific reason.

Category	Function	Use instead
Client setup	createDirectus()	Use useDirectus() — pre-configured with auth(), rest(), realtime(), and SSR cookie forwarding.
Client setup	authentication()	Already configured by useDirectus().
Client setup	rest()	Already configured by useDirectus().
Client setup	realtime()	Already configured by useDirectus().
Client setup	staticToken()	Used internally for adminToken. Import manually if you need a one-off static-token client alongside createDirectus().
Auth	auth()	Low-level realtime auth handler. Use useDirectusAuth() for normal flows.
Auth	getAuthEndpoint()	Internal SDK auth routing helper.
Auth	acceptUserInvite()	Use useDirectusAuth().acceptUserInvite().
Auth	createUser()	Use useDirectusAuth().createUser().
Auth	inviteUser()	Use useDirectusAuth().inviteUser().
Auth	passwordRequest()	Use useDirectusAuth().passwordRequest().
Auth	passwordReset()	Use useDirectusAuth().passwordReset().
Auth	readMe()	Use useDirectusAuth().readMe() — manages shared user state.
Auth	updateMe()	Use useDirectusAuth().updateMe() — manages shared user state.
Files	uploadFiles()	Use uploadDirectusFiles() — handles FormData construction.
Storage	memoryStorage()	Use useDirectusStorage().
GraphQL	graphql()	Not supported by this module. Import manually if needed.
GraphQL	readGraphqlSdl()	Not supported by this module. Import manually if needed.

If you need one of these, import it directly:

import { createDirectus, graphql, rest } from '@directus/sdk'

Disabling or Customizing Auto-Imports

You can turn auto-imports off or narrow the list via the autoImportSdk option in your Nuxt config.

Disable entirely:

export default defineNuxtConfig({
  directus: {
    autoImportSdk: false,
  },
})

Exclude specific functions — useful if a name collides with something else in your app:

export default defineNuxtConfig({
  directus: {
    autoImportSdk: {
      exclude: ['aggregate', 'customEndpoint'],
    },
  },
})

Your exclude is additive: the module's built-in exclusions still apply, and you don't need to repeat them.

Authentication Composables

useDirectusAuth()

Main authentication composable with methods and state for user authentication.

Returns: DirectusAuth

interface DirectusAuth {
  user: Ref<DirectusUser | null>
  loggedIn: ComputedRef<boolean>
  readMe: () => Promise<DirectusUser | null>
  updateMe: (data: UpdateMeInput) => Promise<DirectusUser>
  login: (email: string, password: string, options?: LoginOptions & { redirect?: boolean | RouteLocationRaw }) => Promise<DirectusUser | null>
  loginWithProvider: (provider: string, redirectOnLogin?: boolean | string) => Promise<void>
  logout: (redirect?: boolean | RouteLocationRaw) => Promise<void>
  createUser: (data: RegisterUserInput) => Promise<DirectusUser>
  register: (data: DirectusRegisterInput) => Promise<void>
  inviteUser: (email: string, role: string, inviteUrl?: string) => Promise<void>
  acceptUserInvite: (token: string, password: string) => Promise<void>
  passwordRequest: (email: string, resetUrl?: string) => Promise<void>
  passwordReset: (token: string, password: string) => Promise<void>
}

Example:

const {
  user,
  loggedIn,
  login,
  logout,
  readMe,
  updateMe,
} = useDirectusAuth()

// Login
await login('user@example.com', 'password')

// Check if logged in
if (loggedIn.value) {
  console.log('Logged in as:', user.value.email)
}

// Update user
await updateMe({ first_name: 'John' })

// Logout
await logout()

Properties

user

• Type: Ref<DirectusUser | null>
• Description: Current authenticated user

const { user } = useDirectusAuth()

console.log(user.value?.email)
console.log(user.value?.first_name)
console.log(user.value?.role)

loggedIn

• Type: ComputedRef<boolean>
• Description: Whether a user is currently logged in

const { loggedIn } = useDirectusAuth()

if (loggedIn.value) {
  console.log('User is authenticated')
}

Methods

readMe()

Fetch the current user's data.

Returns: Promise<DirectusUser | null>

const { readMe } = useDirectusAuth()

const user = await readMe()

updateMe(data)

Update the current user's profile.

Parameters:

• data: UpdateMeInput - Fields to update. role and policies are excluded to prevent privilege escalation. avatar accepts a pre-uploaded file ID (string), not a file object — upload the file first, then pass its ID here.

Returns: Promise<DirectusUser>

const { updateMe } = useDirectusAuth()

await updateMe({
  first_name: 'John',
  last_name: 'Doe',
})

// To update avatar, first upload the file, then attach its ID
await updateMe({ avatar: 'file-uuid' })

login(email, password, options?)

Login with email and password.

Parameters:

• email: string - User email
• password: string - User password
• options?: LoginOptions & { redirect?: boolean | RouteLocationRaw } - Login options

Returns: Promise<DirectusUser | null>

const { login } = useDirectusAuth()

// Login with redirect (default)
await login('user@example.com', 'password')

// Login without redirect
await login('user@example.com', 'password', { redirect: false })

// Login with custom redirect
await login('user@example.com', 'password', { redirect: '/dashboard' })

// Login with OTP
await login('user@example.com', 'password', { otp: '123456' })

loginWithProvider(provider, redirectOnLogin?)

Login with SSO/OAuth provider. Note that a redirect is required for SSO authentication, so if you are passing false to redirectOnLogin your browser will still redirect, but you will be redirected to the current page.

Parameters:

• provider: string - Provider name (google, github, microsoft, etc.)
• redirectOnLogin?: string | boolean - URL to redirect to after login

Returns: Promise<void>

const { loginWithProvider } = useDirectusAuth()

// Login with Google
await loginWithProvider('google')

// Login with custom redirect
await loginWithProvider('google', '/dashboard')

// Login with redirect as boolean
await loginWithProvider('google', false)

logout(redirect?)

Logout the current user.

Parameters:

• redirect?: boolean | RouteLocationRaw - Where to redirect after logout

Returns: Promise<void>

const { logout } = useDirectusAuth()

// Logout with default redirect
await logout()

// Logout without redirect
await logout(false)

// Logout with custom redirect
await logout('/login')

register(data)

Public sign-up via POST /users/register. Works without being logged in, but public registration must be enabled in your Directus project settings. Directus returns no body, so log the user in (or send them to verify their email) afterwards.

Parameters:

• data: DirectusRegisterInput
  • email: string
  • password: string
  • first_name?: string
  • last_name?: string
  • verification_url?: string - Where the verification email links to, when email verification is on

Returns: Promise<void>

const { register } = useDirectusAuth()

await register({
  email: 'new@example.com',
  password: 'secure-password',
  first_name: 'John',
  last_name: 'Doe',
})

createUser(data)

Create a user via POST /users. Requires create permission on directus_users, so use it for admin flows rather than public sign-up.

Parameters:

• data: RegisterUserInput - User data

Returns: Promise<DirectusUser>

const { createUser } = useDirectusAuth()

const newUser = await createUser({
  email: 'new@example.com',
  password: 'secure-password',
})

inviteUser(email, role, inviteUrl?)

Invite a new user.

Parameters:

• email: string - User email
• role: string - Role ID or UUID
• inviteUrl?: string - Custom invite URL

Returns: Promise<void>

const { inviteUser } = useDirectusAuth()

await inviteUser(
  'newuser@example.com',
  'role-uuid',
  'https://yourapp.com/accept-invite'
)

acceptUserInvite(token, password)

Accept a user invitation.

Parameters:

• token: string - Invite token
• password: string - New password

Returns: Promise<void>

const { acceptUserInvite } = useDirectusAuth()

await acceptUserInvite('invite-token', 'new-password')

passwordRequest(email, resetUrl?)

Request a password reset.

Parameters:

• email: string - User email
• resetUrl?: string - Custom reset URL

Returns: Promise<void>

const { passwordRequest } = useDirectusAuth()

await passwordRequest(
  'user@example.com',
  'https://yourapp.com/reset-password'
)

passwordReset(token, password)

Reset password with token.

Parameters:

• token: string - Reset token
• password: string - New password

Returns: Promise<void>

const { passwordReset } = useDirectusAuth()

await passwordReset('reset-token', 'new-password')

---

useDirectusUser()

Direct access to the current user state.

Returns: Ref<DirectusUser | null>

const user = useDirectusUser()

console.log(user.value?.email)
console.log(user.value?.first_name)

// Watch for changes
watch(user, (newUser) => {
  if (newUser) {
    console.log('User logged in:', newUser.email)
  }
  else {
    console.log('User logged out')
  }
})

Directus Client Composables

useDirectus()

Get the Directus client instance for making API requests.

Returns: DirectusClient<DirectusSchema>

const directus = useDirectus()

// Read items
const articles = await directus.request(readItems('articles'))

// Create item
const newArticle = await directus.request(createItem('articles', {
  title: 'New Article',
  content: 'Article content...',
}))

// Update item
await directus.request(updateItem('articles', 'item-id', {
  title: 'Updated Title',
}))

// Delete item
await directus.request(deleteItem('articles', 'item-id'))

// Read singleton
const settings = await directus.request(readSingleton('settings'))

// Custom queries
const { data: articles } = await useAsyncData('articles', () =>
  directus.request(readItems('articles', {
    filter: { status: { _eq: 'published' } },
    sort: ['-date_created'],
    limit: 10,
  })))

Common Operations:

const directus = useDirectus()

// Collections
const items = await directus.request(readItems('collection'))
const item = await directus.request(readItem('collection', 'id'))
const created = await directus.request(createItem('collection', data))
const updated = await directus.request(updateItem('collection', 'id', data))
await directus.request(deleteItem('collection', 'id'))

// Singletons
const singleton = await directus.request(readSingleton('settings'))
await directus.request(updateSingleton('settings', data))

---

useDirectusUrl(path?)

Generate full URLs to your Directus instance. This composable is context-aware:

• Client: returns the client URL (or proxy path if proxy is enabled)
• Server (SSR): returns the server URL if configured (for Docker/K8s internal networking), otherwise the client URL
• Proxy: returns window.location.origin + proxyPath on client, or host header-based URL on server

Parameters:

• path?: string - Optional path to append

Returns: string

const directusUrl = useDirectusUrl()
// Client: https://directus.example.com
// Server (with split URL): http://directus:8055

const apiUrl = useDirectusUrl('items/articles')
// Client: https://directus.example.com/items/articles

const assetsUrl = useDirectusUrl('assets')
// Client: https://directus.example.com/assets

---

useDirectusOriginUrl(path?)

Generate URLs to the public-facing Directus instance. Unlike useDirectusUrl, this always returns the client URL; it ignores both proxy and serverDirectusUrl.

Use this when you need the real Directus URL for browser navigation (e.g. SSO redirects, admin links).

Parameters:

• path?: string - Optional path to append

Returns: string

const ssoUrl = useDirectusOriginUrl('/auth/login/google?redirect=...')
// Always: https://directus.example.com/auth/login/google?redirect=...

const adminUrl = useDirectusOriginUrl('admin')
// Always: https://directus.example.com/admin

---

useDirectusPreview()

Control and check preview mode. Preview mode is typically used to show draft/unpublished content when viewing your site with a ?preview=true query parameter.

Returns: Ref<boolean>

const directusPreview = useDirectusPreview()

// Check if preview mode is active
if (directusPreview.value) {
  console.log('Preview mode is enabled')
}

Note: Preview mode is separate from visual editor mode. Preview mode is set automatically by the plugin when ?preview=true is in the URL. Visual editor mode is set automatically when the site is inside a Directus iframe.

<script setup>
const directusPreview = useDirectusPreview()
</script>

<template>
  <div v-if="directusPreview" class="preview-banner">
    Preview Mode — Showing draft content
  </div>
</template>

---

useDirectusVisualEditor()

Check if the visual editor is active (i.e., your site is loaded inside a Directus iframe).

Returns: Ref<boolean>

This composable is set automatically by the Directus plugin — you do not need to set it manually. When visualEditor: true is in your config and the site is inside an iframe, this will be true.

const directusVisualEditor = useDirectusVisualEditor()

if (directusVisualEditor.value) {
  console.log('Inside Directus iframe — editing enabled')
}

Common Usage:

<script setup>
const directusVisualEditor = useDirectusVisualEditor()
</script>

<template>
  <div v-if="directusVisualEditor" class="editor-banner">
    Editing Mode Active
  </div>
</template>

File Composables

uploadDirectusFile(file, query?)

Upload a single file to Directus.

Parameters:

• file: { file: File, data?: Partial<Record<keyof DirectusFile, string>> } - File and metadata
• query?: Query - Directus query options

Returns: Promise<DirectusFile>

const file = event.target.files[0]

const uploaded = await uploadDirectusFile({
  file,
  data: {
    title: 'My Image',
    description: 'Image description',
    folder: 'folder-uuid',
  }
}, {
  fields: ['*'],
})

console.log('Uploaded:', uploaded.id)

---

uploadDirectusFiles(files, query?)

Upload multiple files to Directus.

Parameters:

• files: Array<{ file: File, data?: Partial<Record<keyof DirectusFile, string>> }> - Files and metadata
• query?: Query - Directus query options

Returns: Promise<DirectusFile[] | DirectusFile>

const files = Array.from(event.target.files).map(file => ({
  file,
  data: {
    folder: 'folder-uuid',
  }
}))

const uploaded = await uploadDirectusFiles(files)

console.log('Uploaded files:', uploaded.length)

---

getDirectusFileUrl(file, options?)

Generate a URL for a Directus file with optional transformations.

Parameters:

• file: string | DirectusFile - File ID or file object
• options?: DirectusFileOptions - Transformation options

Returns: string

// Basic URL
const url = getDirectusFileUrl('file-uuid')

// With transformations
const url = getDirectusFileUrl('file-uuid', {
  width: 800,
  height: 600,
  quality: 80,
  fit: 'cover',
  format: 'webp',
})

// From file object
const file = await directus.request(readFile('file-uuid'))
const url = getDirectusFileUrl(file, { width: 400 })

// Download link
const downloadUrl = getDirectusFileUrl(file, {
  download: true,
  filename: 'custom-name.jpg',
})

Options:

interface DirectusFileOptions {
  filename?: string // Custom filename for downloads
  download?: boolean // Force download
  width?: number // Resize width
  height?: number // Resize height
  quality?: number // Image quality (1-100)
  fit?: 'cover' | 'contain' | 'inside' | 'outside'
  format?: 'jpg' | 'png' | 'webp' | 'tiff' | 'avif'
  withoutEnlargement?: boolean // Prevent upscaling
  key?: string // Access key for private files
}

Examples:

// Responsive image sizes
const thumbnail = getDirectusFileUrl(file, { width: 200, format: 'webp' })
const medium = getDirectusFileUrl(file, { width: 800, format: 'webp' })
const large = getDirectusFileUrl(file, { width: 1600, format: 'webp' })

// High-quality cover image
const cover = getDirectusFileUrl(file, {
  width: 1920,
  height: 1080,
  fit: 'cover',
  quality: 90,
  format: 'webp',
})

// Optimized thumbnail
const thumb = getDirectusFileUrl(file, {
  width: 300,
  height: 300,
  fit: 'cover',
  quality: 70,
  format: 'webp',
  withoutEnlargement: true,
})

Storage Composables

useDirectusStorage()

Get the Directus client storage instance (primarily for internal use).

Returns: DirectusStorage

const storage = useDirectusStorage()

// Get item
const token = await storage.get('directus_session_token')

// Set item
await storage.set('directus_session_token', 'token-value')

// Delete item
await storage.delete('directus_session_token')

Note: This composable is mainly used internally for session management. You typically won't need to use it directly.

See Also

• Server-Side Utilities
• Configuration Reference
• Visual Editor Guide
• Directus SDK Documentation