@templatical/media-library

@templatical/media-library

Media library for Templatical — composable, Vue components, and a standalone visual SDK.

Browse, upload, organize, crop, and replace media assets. Used by @templatical/editor's Cloud build, and available as a standalone SDK for any app that needs a media manager.

Install

npm install @templatical/media-library

Peer deps: vue@^3.5, tailwindcss@^4.

Authentication. The media library connects to Templatical Cloud and authenticates against your backend. Your server exposes a token endpoint (returning a short-lived JWT for the current user/project), and you pass that endpoint URL as auth.url. See the authentication guide for the full setup.

Usage

Standalone visual SDK (mount anywhere)

import { init } from '@templatical/media-library';
import '@templatical/media-library/style.css';

const media = await init({
  container: '#media',
  auth: {
    url: 'https://your-app.com/api/templatical/token',
  },
  onSelect(item) {
    console.log('Picked:', item.url);
  },
});

// Later
media.unmount();

Vue component

Use MediaLibraryModal inside a Vue 3 app. See docs for the full prop reference.

import { MediaLibraryModal } from '@templatical/media-library';
import '@templatical/media-library/style.css';

Composable (build your own UI)

import { AuthManager } from '@templatical/core/cloud';
import { useMediaLibrary } from '@templatical/media-library';

const authManager = new AuthManager({
  url: 'https://your-app.com/api/templatical/token',
});
await authManager.initialize();

const lib = useMediaLibrary({
  projectId: authManager.projectId,
  authManager,
});

API client (low-level)

import { AuthManager } from '@templatical/core/cloud';
import { MediaApiClient } from '@templatical/media-library';

const api = new MediaApiClient(authManager);
const response = await api.browseMedia({ folder_id: null });

Exports

• Standalone SDK — init(), unmount()
• Vue components — MediaLibraryModal + 12 sub-components (grid, upload zone, folder tree, preview panel, edit/replace/import modals)
• Composables — useMediaLibrary, useMediaCategories, useMediaPicker, useI18n
• API client — MediaApiClient
• Types — MediaItem, MediaFolder, MediaCategory, MediaConversion, MediaBrowseParams/Response, MediaUsageInfo/Response, MediaConfig, etc.

Inside the editor's Shadow DOM

When the editor mounts in its default shadow-DOM mode (shadowDom: true), the media library invocation teleports into the editor's shadow-aware popover root rather than document.body. The MediaLibraryModal accepts an optional popoverTarget?: HTMLElement | null prop and provides it to its three nested sub-modals (replace, edit, import-url) so the entire media UI lives inside the editor's shadow root. Standalone-SDK consumers (init({ container })) keep the previous body-level mount.

If you embed MediaLibraryModal manually inside another shadow-DOM-mounted UI, pass popoverTarget to keep its sub-modals scoped to your shadow root.

Documentation

• Media library guide
• Shadow DOM (editor)

Full reference at docs.templatical.com.

License

FSL-1.1-MIT — free for any non-competing commercial use, automatically converts to MIT after 2 years per release.