ipcRenderer
ipcRenderer represents the web page's end of the message channel: the page uses it to send messages to the app, ask the app for results, and receive messages from the app.
It is only available in a preload script. A preload script is a JS file specified with webPreferences.preload when creating a WebView, and it runs inside the web page. ipcRenderer is a name directly available in the preload script, not a global of the page: in the page's own scripts, typeof ipcRenderer is 'undefined'. It is not in the app's main.js either.
A preload script usually uses contextBridge.exposeInMainWorld() to attach a few specific methods to the page's window, and those methods call ipcRenderer.
The app's end is webContents: messages sent with send() are received in the ipc-message event, requests sent with invoke() are answered by webContents.ipc.handle(), and messages the app sends with webContents.send() are received by on().
For how to set up this channel, see the guide Messaging between a web page and the app.
Note: The preload script and the page's scripts are not isolated. Any script in the page can send messages into the channel directly without going through
ipcRenderer, and can also impersonate the app so that listeners registered withon()receive fake messages. See Preload scripts.
Functions
ipcRenderer is an object; these are its methods.
Sending messages to the app:
| Method | Description |
|---|---|
send() | Sends a message to the app without waiting for a reply |
invoke() | Asks the app for a result, returning a Promise |
Receiving messages from the app:
| Method | Description |
|---|---|
on() | Receives messages on a channel |
addListener() | Same as on() |
once() | Receives messages on a channel, only once |
off() | Stops receiving |
removeListener() | Same as off() |
removeAllListeners() | Removes the listeners for one channel (or all channels) |
Message arguments and results are passed as JSON; see How values are passed.
Examples
The preload script JS/web/preload.js:
contextBridge.exposeInMainWorld('app', {
share: (id) => ipcRenderer.send('share', id),
getUser: () => ipcRenderer.invoke('get-user'),
});
ipcRenderer.on('theme', (event, name) => {
document.documentElement.dataset.theme = name;
});On the app side:
const web = new WebView({ webPreferences: { preload: 'JS/web/preload.js' } });
const contents = web.webContents;
contents.addEventListener('ipc-message', (e) => {
if (e.channel === 'share') console.log('The page wants to share', e.args[0]);
});
contents.ipc.handle('get-user', () => ({ name: 'Jack' }));
contents.addEventListener('did-finish-load', () => contents.send('theme', 'dark'));Effect
- When the page calls
app.share(42), the app's console printsThe page wants to share 42. - In the page,
await app.getUser()gives{ name: 'Jack' }. - After the page finishes loading,
<html>gainsdata-theme="dark".
The preload script's code runs in the web page, so the snippet above is not type-checked.
Comparison with Electron
| Electron | Here | Difference |
|---|---|---|
const { ipcRenderer } = require('electron') | Use ipcRenderer directly | It is a name directly available in the preload script |
ipcRenderer.send / invoke / on / once / off / removeAllListeners | The same | Arguments are passed as JSON; a listener's event only has sender |
Corresponding iOS API
window.webkit.messageHandlers.<name>.postMessage(), provided in the page by WKScriptMessageHandlerWithReply. ipcRenderer is built on top of it.
See also
contextBridge: attaching the preload script's methods to the page- Preload scripts
WebContents: the app's end