Links
Clickable links on elements, groups and words, and how each export and import format keeps them
A link makes part of a design clickable in the exported file: a whole element or group, or a few words of text. It opens a web page, starts an email or a call, or jumps to another page of the design. Links are part of the design JSON, so they survive store.toJSON() and store.loadJSON(), and the importers bring the links of the source file with them.
You set links from code. The editor keeps them while the user edits, but it has no link button, and a link does nothing on the canvas.
Live demo
The demo adds its own Link button to the toolbar, which reads and writes the selected element's href. Change a link, then download the PDF or open the HTML and click the links in the output.
Set a link
Give any element or group an href:
// the whole button opens the shop
button.set({ href: 'https://example.com/shop' });
// a page jump: the ID of another page, after #
store.activePage.addElement({
type: 'text',
text: 'See the price list',
href: '#' + store.pages[2].id,
});
// remove the link
button.set({ href: undefined });To link a few words, wrap them in <a href> in rich text. Table cells take rich text too:
store.activePage.addElement({
type: 'text',
text: '<p>Questions? <a href="mailto:hello@example.com">Email us</a> or call <a href="tel:+15551234567">+1 555 123 4567</a>.</p>',
width: 800,
fontSize: 32,
});An <a href> can hold a template variable: <a href="https://example.com/u/{{user.id}}">. An element's href takes the text as written.
Link targets
| Target | Example | Opens |
|---|---|---|
| Web page | https://example.com | The URL (http: works too) |
mailto:hello@example.com | A new email | |
| Phone | tel:+15551234567 | A call |
| Page of the design | # and a page ID | That page |
Exports drop any other target, such as javascript: or a relative URL, and the content stays as it is, without a link. A jump to a page that is not in the exported file is dropped too, with a warning, unless the exporter takes pageUrls.
Group links and a child's own link
A group's href applies to each child that has no href of its own, so a child can link somewhere else. In the same way, an <a href> inside a linked text keeps its own target, and the rest of the text follows the element's link.
const banner = store.activePage.addElement({
type: 'image',
src: 'https://example.com/banner.png',
width: 600,
height: 300,
});
// this child opens the map instead of the event page
const directions = store.activePage.addElement({
type: 'text',
text: 'Get directions',
y: 320,
href: 'https://maps.example.com',
});
const group = store.groupElements([banner.id, directions.id]);
group.set({ href: 'https://example.com/event' });Links in exports
| Format | Package or call | Links |
|---|---|---|
| SVG | @polotno/svg-export | <a> around each linked element and around linked words. A jump to a page in another SVG needs pageUrls |
| HTML | @polotno/html-export | Each linked element is a link, and linked words are anchors. Every page carries its ID, so a jump scrolls to it |
@polotno/pdf-export | Link annotations over each linked element and linked words; page jumps go to the page. Elements the vector PDF skips, such as video, get no link | |
| PDF (raster) | store.saveAsPDF(), polotno-node | Link annotations over the same areas; page jumps go to the page |
| PDF/X | @polotno/pdf-export with pdfx | None: print files carry no links |
| PPTX | @polotno/pptx-export | Shape hyperlinks, hyperlinks on text runs, and jumps to a slide. A linked table links its text |
@polotno/email-export | Linked areas and linked words. An email holds one page, so a page jump needs pageUrls | |
| PNG, JPEG, GIF, MP4 | image export, video export, polotno-node | None: put a link around the file on your own page |
Jump to pages published separately
An SVG or an email holds one page, so a jump to another page needs a published address for it. Pass pageUrls, a map from page ID to URL, to jsonToSVG or jsonToEmailHTML. A jump to a page in the map goes to its URL:
import { jsonToSVG } from '@polotno/svg-export';
const svg = await jsonToSVG(
{ ...json, pages: [json.pages[0]] },
{
pageUrls: {
[json.pages[1].id]: 'https://example.com/catalog/page-2',
},
},
);Without an entry, svg-export drops the jump with a console warning, and email-export reports a link-unavailable warning to onWarning.
Links from imports
| Format | Package | What becomes a link | Not imported |
|---|---|---|---|
@polotno/pdf-import | Web, email and phone links, and jumps to a page of the document: on the words they cover, or on the one graphic that fills the link's area | LINK_SKIPPED, with reason unsupported-destination or no-editable-owner | |
| SVG | @polotno/svg-import | <a> around shapes and text (href or xlink:href) | A relative target, unless you pass baseUrl |
| PPTX | @polotno/pptx-import | Click links on shapes and on text, and jumps to another slide | |
| IDML | @polotno/idml-import | Hyperlinks on text and on frames, to a URL or to a page of the document | OBJECT_UNSUPPORTED with kind: 'hyperlink-destination', for a destination outside the document |
| PSD | @polotno/psd-import | A slice's URL, on the one layer the slice covers | A slice that covers no single layer, with a console warning |
An imported page jump points at the imported page, so the design keeps it, and each export above writes it like any other page jump.
An SVG's relative links resolve against its own address. Pass it as baseUrl:
import { svgToJson } from '@polotno/svg-import';
const json = await svgToJson({ svg, baseUrl: 'https://example.com/flyers/' });Read the PDF and IDML warnings through onWarning:
import { pdfToJson } from '@polotno/pdf-import';
const json = await pdfToJson({
pdf: pdfBuffer,
onWarning: (warning) => {
if (warning.code === 'LINK_SKIPPED') {
// 'unsupported-destination': no destination, or an action other than a link
// 'no-editable-owner': no text or single graphic under the link
console.warn(warning.details.reason, warning.details.pageIndex);
}
},
});