Media

Upload images and documents once and use them everywhere: the media manager stores each image at four sizes, converts it to WebP, crops to a ratio or a free shape, keeps PDFs, Word, Excel, PowerPoint, CSV and text files for pages to link to, takes images from the pages of a PDF, and finds anything by its title, notes or alt text.

What it is

The media manager is at Media Manager in the admin menu (/admin/media) and opens as a picker from every image field. It has these tabs:

Where the picker opens:

• The content editor: cover image, image fields, images in the body, and rows of gallery and info card fields (a gallery can take several images in one pick). An image dropped or pasted into the body goes to the library without the picker; see Drop or paste into the editor.
• The content editor's file fields and the body's Attach files command (type / in the body), which open it on Files. See File fields.
• The signup form editor.
• The logo in Settings, About.
• An admin's profile photo. Members upload their photo to their own folder instead (avatars/{uid}/); they never see the library.

The picker is as wide as the window is tall (a wide dialog on a computer) but never wider than the screen. On a phone (and any window up to 768px wide) it takes the screen's width and the tabs become a dropdown. Choosing an image, icon or file opens its details over the images, with Insert; Back returns to the images. When the picker takes several at once, picking keeps the images in view and Insert is in a bar below them. Crop and Take an image open their step at the top, and Cancel in the crop step returns to the details. The Media Manager page works the same way.

Turn it on or off

Media is always on. It is core and belongs to no switchable feature.

Set it up

Nothing is needed: uploads work on a new install. To change the limits, open Settings > Misc, Media Upload:

To offer Unsplash, add an Unsplash access key under Settings > Integrations; the page has a setup guide. For choosing and organizing a website's images, see Manage media.

Use it

Upload

The manager accepts JPEG, PNG, WebP and GIF. Each file is processed in the browser, then uploaded:

1. It is resized to four sizes, each a limit on the longest side, so a size means the same box for landscape and portrait photos.

2. It is encoded as WebP (unless conversion is off). A size the image is too small for is not enlarged; sizes with the same pixel size share one file.

3. The largest file is checked against the file size limit. Too large, and the upload stops with a message.

4. The files go to Storage and one media document records them.

GIFs are stored once, as they are, so animation survives: they have no sizes.

Files

The Files tab keeps documents for pages to link to. Drop files on the Upload file card, or choose them (several at once). The type is decided by the file's extension, not by what the browser reports, and only these are taken:

• Files can be up to 20 MB each. There is no setting for it: documents are stored as they are, not resized like images.
• Pages, SVG, scripts, ZIP archives and macro files (.docm, .xlsm) are refused, with a message naming the file. The storage rules refuse them too.
• Each file gets a title from its name ("Annual-Report_2025.pdf" becomes "Annual Report 2025"). The title is what the library shows, the link text on pages, and the name a download is saved under.
• A PDF shows its first page on its card and its page count in the panel. A PDF locked with a password, or one that cannot be read, still uploads; it shows a PDF icon instead.

Select a file to see its panel: type, size, pages, upload date and stored name, its details, and Copy link, Open and Delete. A PDF also has Take an image. Word and PowerPoint files say to save them as a PDF to take images from them.

Take an image from a PDF

Pull a photo or a chart out of a brochure without another program. Open a PDF one of these ways:

• In any image picker (Insert image in the body, an image or gallery field): the From a PDF tab. See From a PDF.
• On the Media Manager page: drop or choose a PDF on My Uploads, or select one in Files and press Take an image.

A PDF from your computer opens at once and is kept in Files once it has opened, so you can come back to it. The same PDF (same file name and size) is not stored twice, and a PDF that will not open (locked or broken) is not kept. Each image records the PDF and page it came from, when the PDF is in Files.

1. The pages show as a grid, drawn as they come into view, so a long PDF opens quickly.

2. Click a page. It opens in the same crop step as Crop, with the pictures on the page outlined and numbered. The frame starts on the first picture not taken yet, reading top to bottom, then left to right.

3. Click another outline (or a picture's number) and the frame takes that picture's exact edges (with a fixed ratio picked, the largest frame of that ratio centred on it), or drag the frame anywhere; a press inside the frame always moves it, for a label, a chart or part of a photo. Pictures already taken in this visit show a tick.

4. Zoom with the minus and plus buttons, Ctrl or Cmd with the mouse wheel (a trackpad pinch works the same way in Chrome, Edge and Firefox, not in Safari), a two-finger pinch on a touch screen, or the + and - keys while the frame has focus; drag outside the frame to move around. The page is drawn again with more detail as you zoom. Move between pages with the arrows, by typing a page number, or with Page Up and Page Down; All pages goes back to the grid.

5. Save as image (in a picker, Insert or Save, take another) draws only the framed part again, at the XL size, and uploads it like any image: every size, WebP when that is on, named after the PDF and the page ("Brochure, page 3"; a second one from the page is "Brochure, page 3 (2)"). Text and drawings come out sharp; a photo inside the PDF is only as sharp as the photo the PDF holds, and the usual note says when the result is smaller than the size picked.

6. After a save the page stays open, with the frame on the next picture not taken. On the Media Manager page, Done on the page grid opens My Uploads with the newest image selected.

The PDF is never changed, and what is saved is always the framed part as the page shows it: never text, and never a picture's own file pulled out of the PDF. A PDF locked with a password says so and asks you to remove the password first; there is no password box.

Pictures are found from how the page is drawn, so they are exact to the point. Some things are not offered, and need a dragged frame:

• Artwork drawn with shapes, such as charts, logos and illustrations, rather than a picture.
• A scanned page: the whole page is one picture, so nothing on it is offered.
• Small pictures (under two thirds of an inch on a side), such as icons and bullets.

A picture partly hidden by a shape, such as a photo in a circle, is outlined at its full size; drag the frame in if you want less. Pieces of one photo cut into strips are joined into one.

From a PDF

The tab every image picker has for taking images from a PDF and inserting them, made for a brochure whose photos go in different places on a page:

1. Choose Insert image (or open any image field's picker) and click From a PDF. It lists the PDFs in Files, newest first, with the one you used last first of all, under Choose a PDF from your computer (or drop one on the tab). With more than six, a search box finds them by title, notes or file name.

2. Click a PDF, then a page. Frame a picture as in Take an image from a PDF, and if you like, type its alt text and pick the size.

3. Press Insert. The image is saved to My Uploads and goes in, at that size and with that alt text.

4. For the next photo, choose Insert image again: the picker opens on the same PDF and page, at the same zoom, with the frame on the next picture not taken. Press Insert.

The picker opens on the PDF only when the last image you chose came from one; choose an image from another tab and it opens as usual again. A picker that asks for its own first tab (an icon field, for example) always opens there. This is remembered in the browser tab until you reload the admin, and the PDF is read from Storage once per visit, not each time the picker opens. In the body, the cursor moves past each inserted image, so the next one goes after it.

Save, take another saves without inserting, for photos you will use later; they are in My Uploads. In a field that takes several images (a gallery), Insert adds every image taken in that visit, from any PDF, in order, and says how many.

Details and search

Every image and file has details, edited in its panel and saved when you leave the field:

The search box on My Uploads and Files finds items whose title, notes, alt text or file name hold every word typed, in any order, ignoring case and accents ("pune brochure" finds "Spring brochure" with the note "For the Pune store"). The first search loads the tab's details once; clear the box to page through the library again. Images uploaded before details existed show their file name until given a title.

Drop or paste into the editor

Drop an image onto the rich text editor, or paste one (a screenshot, or an image copied in a browser), and it is uploaded exactly as above: the same settings, sizes, WebP conversion and media document, so it shows in My Uploads. While it uploads, a box where it was dropped shows the file name and how far the upload has got. The image then goes in at M, the size Insert image gives unless you choose. Several images dropped together upload one after another and keep their order.

• A file of the wrong type or too large is not added, and a message says why.
• If the upload worked but its media document could not be saved, the image still goes in, and a message says it is not in My Uploads.
• A paste that carries text as well, such as cells copied from a spreadsheet or a passage from a word processor, pastes the text, not the picture of it those programs also put on the clipboard.
• A document the library takes (PDF, Word, Excel, PowerPoint, CSV or text) is uploaded to Files the same way and goes in as a file card: a link with the file's title, type and size.
• Any other file is not added, and a message says it cannot be uploaded.

The editor never puts an image's bytes into the content (as a data: URL): that would make the entry document large, towards Firestore's 1 MiB limit, and skip the sizes.

Pick an image

In the picker, choose an image and a size (S, M, L or XL), then confirm. The field stores that size's URL. Templates can still use any other size of the same image through {{ key_s }} to {{ key_xl }}; see Templates.

Crop

Select one image and press Crop under its preview. The crop step takes the place of the grid:

• Pick a ratio: Free, Original (the image's own shape), 1:1, 4:3, 3:4, 3:2 or 16:9. The frame starts as the largest centred one of that shape (Free starts as the whole image).
• Drag inside the frame to move it, and drag a corner or an edge to resize it. With a ratio, every handle keeps it. The arrow keys move the focused frame, with Shift for bigger steps.
• Below the image is the size the crop will be. When it is smaller than the size picked in the side panel, a note says so: the image is never enlarged, so it may look soft in a large space.

What applying a crop does depends on where the image comes from:

Crop is not offered for GIFs (it would drop the animation), or when the picker is choosing several images at once.

Delete

Deleting an image removes every stored size from Storage and the media document. Deleting a file removes it, its first-page picture and its mediaFiles document; images taken from it stay.

Move media to another project

Data > Export Files and Import Files copy images and files, with their titles, alt text and notes; see Data import and export.

Extend it

• Open the picker from your own admin page by opening MediaManagerComponent (in src/app/pages/admin/(media)/media.page.ts) as a dialog with mediaPickerDialogConfig({ isDialogOpen: true }) from src/app/pages/admin/(media)/media-picker-dialog.ts, which gives it the picker's size, so it fits a phone, and its styles: dialog.open(MediaManagerComponent, mediaPickerDialogConfig({ isDialogOpen: true })). Options: multiple (several images or files), size (the preselected size), cropRatio (the ratio the crop frame opens with, such as '1:1' for a square slot; Free when omitted), allowIcons, allowImages and allowFiles (which tabs show; files are off unless asked for, so a caller that only knows images never gets a document), and initialTab. It returns mediaUrl, mediaUrls, size and kind; for an image with alt text, alt; for files, file (or files with multiple), each { id, url, title, type, bytes, pages }, with mediaUrl the first file's URL. For a files-only picker pass { isDialogOpen: true, allowFiles: true, allowImages: false, initialTab: 'files' }.
• Upload an image from your own admin code the way a drop into the editor does with EditorImageUploadService.upload(file, onProgress) (in src/shared/components/tiptap-editor/service/editor-image-upload.service.ts). It reads the settings, uploads every size, writes the media document and resolves to the M size's URL; it rejects with a message fit to show for a wrong type or a file too large.
• Upload a document the same way with EditorImageUploadService.uploadDocument(file, onProgress): it goes to Files with its mediaFiles document and resolves to { url, title, type, bytes, pages }.
• The allowed types, the 20 MB limit and the helpers (allowedFileOf, defaultTitle, formatBytes, isSameUpload) are in src/shared/utils/media-files.ts; openPdf in src/shared/utils/pdf-pages.ts draws PDF pages in the browser (pdf.js, loaded only when used), and its findPictures(page) gives the pictures on a page in reading order, in page points (picturesFromOperators does the work, snapFrame fits a frame of a ratio on one).
• The crop frame, ImageCropperComponent (in src/shared/components/image-cropper/), takes three optional inputs besides src and ratio: frame (a frame to place, in image pixels), zoom (1 fits the image; with zoomable on, the wheel, a pinch and the keys ask for another zoom through zoomChange) and marks (outlines to click, reported by markPicked).
• Files your app lets members upload belong in their own folders under rules you write in storage.app.rules. See Set security rules and indexes.

What it stores

Resizing and cropping happen in the browser; no function processes uploads. To crop an upload, the browser gets its XL file's bytes through readMediaImage, because a canvas may only export an image its page is allowed to read, and a Storage bucket sends no cross-origin header unless it was given a CORS setup. The crop frame itself shows the image by its normal URL, so it appears at once; the bytes are fetched on Save cropped copy. A PDF's pages are drawn with pdf.js the same way: from the file on your computer, from this visit's upload, or through readMediaFile.

Who can do what

Storage is public to read because published pages show the images and link to the files. The details are staff only so notes stay private; pages never read them. See Security rules.

Troubleshooting