Skip to main content

Editor Configuration

@ydesign/react-editor exposes a small set of global configuration APIs to tune the editor's runtime behavior: upload strategy, backend host, i18n, fonts, color presets, timeouts, and so on. They are different from the Customizations chapter — customizations are about replacing or trimming UI, while the APIs in this page are "set once, applied globally" switches.

💡 Every API on this page comes from the real source code. They should be called before createDesignEditorApp(...) so the editor picks up the right configuration on initialization.

How to change image upload behavior?​

The default SidePanel component ships an Upload tab that imports local images into the project. Out of the box, it converts the local file into a base64 string and embeds it directly into the image element.

base64 works, but it makes your design JSON balloon quickly — a 2MB image alone can push a JSON past 3MB. We strongly recommend wiring up your own object storage (S3 / OSS / COS / your own image server). Upload to the server first, then store only the short URL in the JSON: smaller payloads, faster loading, and CDN-friendly.

import { setUploadFunc } from '@ydesign/react-editor/side-panel/upload-panel';

// Signature: (file: File) => Promise<string>
async function upload(localFile: File) {
  const formData = new FormData();
  formData.append('files[]', localFile);

  const res = await fetch('https://your-api.com/upload', {
    method: 'POST',
    body: formData,
  });
  const { url } = await res.json();

  // Must return a usable URL string
  return url;
}

setUploadFunc(upload);

After this is registered, every image picked from the Upload panel goes through your function, and the editor uses the returned URL directly.

Switch the backend host / replace an endpoint​

@ydesign/react-editor ships a few built-in endpoints (font list, template list, image upload, AI eraser, etc.). If your backend lives at a different host, one line is enough:

import { setBaseURL } from '@ydesign/react-editor';

setBaseURL('https://api.your-company.com');

If a specific endpoint has a different path or shape, override it individually:

import { setAPI } from '@ydesign/react-editor';

// Point template list to your own backend
setAPI('templateList', () => ({
  url: 'https://your-api.com/v2/design-templates',
}));

// Override the upload endpoint (method / url / data are all supported)
setAPI('uploadImage', () => ({
  method: 'POST',
  url: 'https://your-api.com/assets/upload',
}));

Overridable endpoint keys: fontList, templateList, templateDetail, uploadImage, psdParse, createRecord, updateRecord, recordDetail, resourcesDetail, teamFontList, inpaint.

How to translate the UI?​

To translate the UI into another language or just tweak some labels:

import { setTranslations } from '@ydesign/react-editor';

setTranslations({
  sidePanel: {
    text: 'Текст',
    myFonts: 'Мои шрифты',
  },
});

If you need the full key schema (helpful when translating to a new language):

import { getTranslations } from '@ydesign/react-editor';

console.log(getTranslations());

📮 If you finish a complete translation for a language, please share it back via a GitHub Issue or PR. It helps @ydesign ship better default translations and saves time for everyone else.

The same translation API can also localize your own custom components:

import { observer } from 'mobx-react-lite';
import { t } from '@ydesign/react-editor/utils/l10n';

const App = observer(() => {
  return <div>{t('sidePanel.yourLabel')}</div>;
  // sidePanel.yourLabel is a key in the translation dictionary
});

t is an alias of translate — fully equivalent.

How to manage fonts?​

In @ydesign there are three font sources:

  1. Google Fonts
  2. User fonts — added via store.fonts, serialized with the design
  3. Global fonts — added via global APIs, available to every user, but not included in the design JSON

(1) Google Fonts​

By default, @ydesign will load fonts from Google Fonts. Each font ships with 4 default variants: regular / italic / bold / bold-italic. If you only need a subset (to save bandwidth):

import { setGoogleFontsVariants } from '@ydesign/react-editor';

// Default value
setGoogleFontsVariants('400,400italic,700,700italic');

// Load only regular and thin
setGoogleFontsVariants('400,100');

Read the current variants:

import { getGoogleFontsVariants } from '@ydesign/react-editor';

console.log(getGoogleFontsVariants()); // '400,400italic,700,700italic'

If you need the raw Google Fonts CSS URL (for previewing in your custom UI for example):

import { getGoogleFontsUrl, injectGoogleFont } from '@ydesign/react-editor';

const url = getGoogleFontsUrl('Roboto');
// → https://fonts.googleapis.com/css?family=Roboto:400,400italic,700,700italic

// Or inject the font into the page directly
injectGoogleFont('Roboto');

(2) User fonts​

To add or remove fonts for the current user, use the Store Fonts API.

Fonts added through store.fonts are exported via store.toJSON(). That means when another user opens the same design, the same fonts are loaded automatically. End users can also manage them from the default "Text" side panel under the "Fonts" tab.

(3) Global fonts​

If you have fonts that should be available to all users (e.g. your brand typeface), use the global API:

import { addGlobalFont } from '@ydesign/react-editor';

// Add by URL
addGlobalFont({
  fontFamily: 'MyCustomFont',
  url: 'https://your-cdn.com/fonts/MyCustomFont.woff2',
});

// Or with fine-grained control over weights / styles
addGlobalFont({
  fontFamily: 'MyCustomFont',
  styles: [
    {
      src: 'url(https://your-cdn.com/fonts/MyCustomFont-Regular.ttf)',
      fontStyle: 'normal',
      fontWeight: 'normal',
    },
    {
      src: 'url(https://your-cdn.com/fonts/MyCustomFont-Bold.ttf)',
      fontStyle: 'normal',
      fontWeight: 'bold',
    },
  ],
});

// If a font is already loaded externally via CSS, just register it.
// It will then appear in the toolbar font dropdown.
addGlobalFont({
  fontFamily: 'MyCustomFont',
});

Removal and replacement:

import { removeGlobalFont, replaceGlobalFonts } from '@ydesign/react-editor';

// Remove a single font
removeGlobalFont('MyCustomFont');

// Replace the whole global font list at once
replaceGlobalFonts([
  { fontFamily: 'Inter', url: 'https://your-cdn.com/Inter.woff2' },
  { fontFamily: 'Roboto Mono', url: 'https://your-cdn.com/RobotoMono.woff2' },
]);

⚠️ Global fonts are NOT included in store.toJSON(). When the design is reopened in an environment that hasn't called addGlobalFont, the font reference will be lost. If a font must follow the design, register it via store.fonts instead.

Font load timeout callback​

Fonts come from the network and occasionally fail to load. Showing a toast is a sensible default:

import { setFontLoadTimeoutCallback, setFontLoadTimeout } from '@ydesign/react-editor';
import { message } from 'antd';

// Load timeout in milliseconds
setFontLoadTimeout(15_000);

// Callback when a font fails to load in time. `msg` includes the font name.
setFontLoadTimeoutCallback(msg => {
  message.warning(msg);
});

Asset load timeout​

Beyond fonts, the editor also loads images / SVGs / template JSON over the network. They share a global timeout:

import { setAssetLoadTimeout, getAssetLoadTimeout } from '@ydesign/react-editor';

setAssetLoadTimeout(30_000); // 30s
console.log(getAssetLoadTimeout()); // 30000

Change default preset colors in the background panel​

The "Background" panel ships with a default palette. If your product has a brand or theme, swap it in one call:

import { setBackgroundColorsPreset } from '@ydesign/react-editor/side-panel/background-panel';

setBackgroundColorsPreset([
  '#ffffff',
  '#000000',
  '#f5f5f5',
  '#ff4d4f',
  '#1677ff',
  '#52c41a',
]);

Register a custom toolbar component​

The toolbar renders different controls depending on the selected element type (textbox, image, path, …). If you've added a new element type or want to replace the toolbar of an existing one:

import { registerToolbarComponent } from '@ydesign/react-editor/toolbar';
import { MyQRCodeToolbar } from './my-qrcode-toolbar';

// Show MyQRCodeToolbar when a 'qrcode' element is selected
registerToolbarComponent('qrcode', MyQRCodeToolbar);

Toolbar components receive { store } as props, so you can act on store.selectedElements from there.

When should I call these APIs?​

All of them are process-level singletons. Call them once at your app entry, before createDesignEditorApp(...):

// app.tsx
import { setBaseURL, setTranslations, addGlobalFont, setUploadFunc, createDesignEditorApp } from '@ydesign/react-editor';
import zhCN from './i18n/zh-CN.json';

// 1) Configure globals
setBaseURL(import.meta.env.VITE_API_BASE);
setTranslations(zhCN);
addGlobalFont({ fontFamily: 'Brand-Sans', url: '/fonts/brand.woff2' });
setUploadFunc(myUpload);

// 2) Boot the editor
createDesignEditorApp({
  container: document.getElementById('root')!,
  key: 'YOUR_API_KEY',
});

Further reading​