@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 behind a MediaProvider (the editor bundles the Browse UI — you do not install this package for init({ media })), and available as a standalone SDK for any app that needs a media manager.

Install

npm install @templatical/media-library

Peer dep: vue@^3.5. Not needed next to @templatical/editor — that package already contains the modal.

Storage. The library is storage-agnostic. Pass a MediaProvider — Cloud's adapter is createCloudMediaProvider from @templatical/core/cloud. See the media contract.

Usage

Standalone visual SDK (mount anywhere)

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

const media = await init({
  container: '#media',
  provider: createCloudMediaProvider(authManager),
  onSelect(asset) {
    console.log('Picked:', asset.url);
  },
});

// Later
media.unmount();

onSelect is optional. accept narrows categories; omit it for every category. Any object implementing MediaProvider works — Cloud is one adapter.

Vue component

Use MediaLibraryModal inside a Vue 3 app. See the media contract for the provider the modal sits on.

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

<MediaLibraryModal
  :visible="open"
  :provider="provider"
  :on-error="onError"
  @select="onSelect"
  @close="open = false"
/>

Composable (build your own UI)

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

const lib = useMediaLibrary({
  provider: createCloudMediaProvider(authManager),
  onError(error) {
    console.error(error);
  },
});

API client (low-level)

For server-side or programmatic media operations, MediaApiClient is exported from @templatical/core/cloud. createCloudMediaProvider maps the response onto MediaProvider.

import { MediaApiClient, createCloudMediaProvider } from '@templatical/core/cloud';

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

const provider = createCloudMediaProvider(authManager);
const page = await provider.list();

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
• Types — MediaAsset, MediaFolder, MediaCategory, MediaRequestContext, MediaUsageInfo, MediaResult (re-exported from @templatical/types)

The MediaProvider / MediaAsset contract lives in @templatical/types.

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 })) mount at document.body.

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 contract
• 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.