Skip to content

🎥 Make videos programmatically with React

New package: `@remotion/mac-cursors` (#10463)

Jonny Burgerd929d5e5d79c
diff --git a/bun.lock b/bun.lock
index 8c9043abcf..a2fa60cba8 100644
--- a/bun.lock
+++ b/bun.lock
@@ -524,6 +524,7 @@
"@remotion/licensing": "workspace:*",
"@remotion/light-leaks": "workspace:*",
"@remotion/lottie": "workspace:*",
+ "@remotion/mac-cursors": "workspace:*",
"@remotion/media": "workspace:*",
"@remotion/media-parser": "workspace:*",
"@remotion/media-utils": "workspace:*",
diff --git a/packages/docs/components/TableOfContents/api.tsx b/packages/docs/components/TableOfContents/api.tsx
index 17920dff19..dd6f95c5d1 100644
--- a/packages/docs/components/TableOfContents/api.tsx
+++ b/packages/docs/components/TableOfContents/api.tsx
@@ -15,6 +15,7 @@ import {TableOfContents as LayoutUtilsTableOfContents} from '../../docs/layout-u
import {TableOfContents as LicensingTableOfContents} from '../../docs/licensing/TableOfContents';
import {TableOfContents as LightLeaksTableOfContents} from '../../docs/light-leaks/table-of-contents';
import {TableOfContents as LottieTableOfContents} from '../../docs/lottie/table-of-contents';
+import {TableOfContents as MacCursorsTableOfContents} from '../../docs/mac-cursors/table-of-contents';
import {TableOfContents as MediaParserTableOfContents} from '../../docs/media-parser/TableOfContents';
import {TableOfContents as MediaUtilsTableOfContents} from '../../docs/media-utils/table-of-contents';
import {TableOfContents as NewVideoTableOfContents} from '../../docs/media/table-of-contents';
@@ -32,8 +33,8 @@ import {TableOfContents as SfxTableOfContents} from '../../docs/sfx/table-of-con
import {TableOfContents as ShapesTableOfContents} from '../../docs/shapes/table-of-contents';
import {TableOfContents as SkiaTableOfContents} from '../../docs/skia/TableOfContents';
import {TableOfContents as StarburstTableOfContents} from '../../docs/starburst/table-of-contents';
-import {TableOfContents as StudioTableOfContents} from '../../docs/studio/TableOfContents';
import {TableOfContents as StudioProtocolTableOfContents} from '../../docs/studio-protocol/table-of-contents';
+import {TableOfContents as StudioTableOfContents} from '../../docs/studio/TableOfContents';
import {TableOfContents as TailwindV4TableOfContents} from '../../docs/tailwind-v4/TableOfContents';
import {TableOfContents as TailwindTableOfContents} from '../../docs/tailwind/TableOfContents';
import {TableOfContents as ThreeTableOfContents} from '../../docs/three/TableOfContents';
@@ -118,6 +119,9 @@ export const TableOfContents: React.FC = () => {
<h2>@remotion/lottie</h2>
<p>Include a Lottie animation in your video</p>
<LottieTableOfContents apisOnly />
+ <h2>@remotion/mac-cursors</h2>
+ <p>Render macOS and custom CSS cursors.</p>
+ <MacCursorsTableOfContents />
<h2>@remotion/media</h2>
<p>
An experimental <code>&lt;NewVideo /&gt;</code> tag for embedding
diff --git a/packages/docs/docs/mac-cursors/index.mdx b/packages/docs/docs/mac-cursors/index.mdx
new file mode 100644
index 0000000000..e74d9d3229
--- /dev/null
+++ b/packages/docs/docs/mac-cursors/index.mdx
@@ -0,0 +1,23 @@
+---
+image: /generated/articles-docs-mac-cursors-index.png
+id: mac-cursors-api
+slug: /mac-cursors
+title: '@remotion/mac-cursors'
+crumb: API
+---
+
+# @remotion/mac-cursors<AvailableFrom v="4.0.513" />
+
+Render bundled macOS cursors and CSS custom cursors in Remotion.
+
+import {TableOfContents} from './table-of-contents';
+
+<Installation pkg="@remotion/mac-cursors" />
+
+## APIs
+
+<TableOfContents />
+
+## License
+
+[Remotion License](/docs/license)
diff --git a/packages/docs/docs/mac-cursors/mac-os-cursor-table.tsx b/packages/docs/docs/mac-cursors/mac-os-cursor-table.tsx
new file mode 100644
index 0000000000..c1ad7ffbfd
--- /dev/null
+++ b/packages/docs/docs/mac-cursors/mac-os-cursor-table.tsx
@@ -0,0 +1,115 @@
+import {MacOSCursor} from '@remotion/mac-cursors';
+import {Thumbnail} from '@remotion/player';
+import React from 'react';
+
+const cursors = [
+ 'alias',
+ 'all-scroll',
+ 'auto',
+ 'beachball',
+ 'busy',
+ 'cell',
+ 'col-resize',
+ 'context-menu',
+ 'copy',
+ 'crosshair',
+ 'e-resize',
+ 'grab',
+ 'grabbing',
+ 'handpointing',
+ 'help',
+ 'n-resize',
+ 'ne-resize',
+ 'nesw-resize',
+ 'no-drop',
+ 'ns-resize',
+ 'nw-resize',
+ 'nwse-resize',
+ 'poof',
+ 'resizedown',
+ 'resizeleft',
+ 'resizeright',
+ 'resizesouth',
+ 'resizesoutheast',
+ 'resizesouthwest',
+ 'resizeup',
+ 'resizeupdown',
+ 'resizewest',
+ 'resizewesteast',
+ 'screenshotselection',
+ 'screenshotwindow',
+ 'text',
+ 'textcursorvertical',
+ 'zoom-in',
+ 'zoom-out',
+];
+
+const hotspotStyle: React.CSSProperties = {
+ position: 'absolute',
+ backgroundColor: '#ff2d8d',
+};
+
+const CursorPreview: React.FC<{readonly cursor: string}> = ({cursor}) => {
+ return (
+ <>
+ <MacOSCursor cursor={cursor} style={{left: 48, top: 32, scale: 1.5}} />
+ <div
+ style={{
+ ...hotspotStyle,
+ left: 41,
+ top: 31,
+ width: 14,
+ height: 2,
+ }}
+ />
+ <div
+ style={{
+ ...hotspotStyle,
+ left: 47,
+ top: 25,
+ width: 2,
+ height: 14,
+ }}
+ />
+ </>
+ );
+};
+
+export const MacOSCursorTable: React.FC = () => {
+ return (
+ <table>
+ <thead>
+ <tr>
+ <th>Cursor</th>
+ <th>Preview</th>
+ </tr>
+ </thead>
+ <tbody>
+ {cursors.map((cursor) => (
+ <tr key={cursor}>
+ <td>
+ <code>{cursor}</code>
+ </td>
+ <td>
+ <Thumbnail
+ component={CursorPreview}
+ inputProps={{cursor}}
+ compositionWidth={96}
+ compositionHeight={64}
+ durationInFrames={1}
+ fps={30}
+ frameToDisplay={0}
+ noSuspense
+ style={{
+ width: 96,
+ height: 64,
+ backgroundColor: 'transparent',
+ }}
+ />
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ );
+};
diff --git a/packages/docs/docs/mac-cursors/mac-os-cursor.mdx b/packages/docs/docs/mac-cursors/mac-os-cursor.mdx
new file mode 100644
index 0000000000..31082bc845
--- /dev/null
+++ b/packages/docs/docs/mac-cursors/mac-os-cursor.mdx
@@ -0,0 +1,86 @@
+---
+image: /generated/articles-docs-mac-cursors-mac-os-cursor.png
+id: mac-os-cursor
+slug: /mac-cursors/mac-os-cursor
+title: '<MacOSCursor>'
+crumb: '@remotion/mac-cursors'
+---
+
+# &lt;MacOSCursor&gt;<AvailableFrom v="4.0.513" />
+
+Renders a macOS cursor with its hotspot placed at the component origin.
+
+Named CSS cursors use SVGs bundled with the package. Custom cursors use the supplied image and hotspot.
+
+import {MacOSCursorTable} from './mac-os-cursor-table';
+
+## Included cursors
+
+The package includes 39 cursor assets. The pink crosshair marks the hotspot that is placed at the component origin.
+
+<MacOSCursorTable />
+
+## Example
+
+```tsx twoslash title="Cursor.tsx"
+import {MacOSCursor} from '@remotion/mac-cursors';
+
+export const Cursor = () => {
+ return (
+ <MacOSCursor
+ cursor="pointer"
+ style={{left: 200, top: 300, scale: 2}}
+ />
+ );
+};
+```
+
+Custom cursors may be quoted or unquoted and may include a hotspot:
+
+```tsx twoslash title="CustomCursor.tsx"
+import {MacOSCursor} from '@remotion/mac-cursors';
+
+const src = 'data:image/svg+xml;base64,PHN2Zy8+';
+
+export const CustomCursor = () => {
+ return (
+ <MacOSCursor
+ cursor="custom"
+ customCursor={`url("${src}") 12 8, pointer`}
+ />
+ );
+};
+```
+
+## API
+
+### `cursor?`
+
+A CSS cursor name such as `"default"`, `"pointer"`, or `"text"`. Set it to `"custom"` to use the `customCursor` prop. Default: `"default"`.
+
+Unknown cursor keywords render the default arrow. `"none"` renders nothing.
+
+### `customCursor?`
+
+A CSS custom cursor value such as `url("...") 12 8, pointer`. It is used when `cursor` is set to `"custom"`.
+
+### `className?`
+
+A CSS class name for the cursor image.
+
+### `style?`
+
+CSS styles for the cursor image. Use `left` and `top` to position it without changing the hotspot correction.
+
+### Timing and display props
+
+The component also accepts [`InteractiveBaseProps`](/docs/interactive#interactivebaseprops), including `durationInFrames`, `from`, `trimBefore`, `freeze`, `hidden`, `name`, and `showInTimeline`.
+
+## Compatibility
+
+<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering serverSideRendering player studio hideServers />
+
+## See also
+
+- [`<Img>`](/docs/img)
+- [Source code for this component](https://github.com/remotion-dev/remotion/blob/main/packages/mac-cursors/src/MacOSCursor.tsx)
diff --git a/packages/docs/docs/mac-cursors/table-of-contents.tsx b/packages/docs/docs/mac-cursors/table-of-contents.tsx
new file mode 100644
index 0000000000..8a678b4483
--- /dev/null
+++ b/packages/docs/docs/mac-cursors/table-of-contents.tsx
@@ -0,0 +1,14 @@
+import React from 'react';
+import {Grid} from '../../components/TableOfContents/Grid';
+import {TOCItem} from '../../components/TableOfContents/TOCItem';
+
+export const TableOfContents: React.FC = () => {
+ return (
+ <Grid>
+ <TOCItem link="/docs/mac-cursors/mac-os-cursor">
+ <strong>{'<MacOSCursor>'}</strong>
+ <div>Render a macOS or custom CSS cursor</div>
+ </TOCItem>
+ </Grid>
+ );
+};
diff --git a/packages/docs/package.json b/packages/docs/package.json
index 97d22f49f2..e1130f9361 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -65,6 +65,7 @@
"@remotion/layout-utils": "workspace:*",
"@remotion/licensing": "workspace:*",
"@remotion/light-leaks": "workspace:*",
+ "@remotion/mac-cursors": "workspace:*",
"@remotion/rough-notation": "workspace:*",
"@remotion/lottie": "workspace:*",
"@remotion/media": "workspace:*",
diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts
index 989da048b5..e0d40a8d3a 100644
--- a/packages/docs/sidebars.ts
+++ b/packages/docs/sidebars.ts
@@ -492,6 +492,15 @@ const sidebars: SidebarsConfig = {
'lottie/lottie-lottiefiles',
],
},
+ {
+ type: 'category',
+ label: '@remotion/mac-cursors',
+ link: {
+ type: 'doc',
+ id: 'mac-cursors/mac-cursors-api',
+ },
+ items: ['mac-cursors/mac-os-cursor'],
+ },
{
type: 'category',
label: '@remotion/media',
diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.ts
index 5700a3bbb2..e5b05f20e4 100644
--- a/packages/docs/src/data/articles.ts
+++ b/packages/docs/src/data/articles.ts
@@ -4139,6 +4139,24 @@ export const articles = [
noAi: false,
slug: 'lovable-for-motion-graphics',
},
+ {
+ id: 'mac-cursors-api',
+ title: '@remotion/mac-cursors',
+ relativePath: 'docs/mac-cursors/index.mdx',
+ compId: 'articles-docs-mac-cursors-index',
+ crumb: 'API',
+ noAi: false,
+ slug: 'mac-cursors',
+ },
+ {
+ id: 'mac-os-cursor',
+ title: '<MacOSCursor>',
+ relativePath: 'docs/mac-cursors/mac-os-cursor.mdx',
+ compId: 'articles-docs-mac-cursors-mac-os-cursor',
+ crumb: '@remotion/mac-cursors',
+ noAi: false,
+ slug: 'mac-cursors/mac-os-cursor',
+ },
{
id: 'maps',
title: 'Map animations in Remotion',
diff --git a/packages/docs/static/generated/articles-docs-mac-cursors-index.png b/packages/docs/static/generated/articles-docs-mac-cursors-index.png
new file mode 100644
index 0000000000..8d388e79ad
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-mac-cursors-index.png differ
diff --git a/packages/docs/static/generated/articles-docs-mac-cursors-mac-os-cursor.png b/packages/docs/static/generated/articles-docs-mac-cursors-mac-os-cursor.png
new file mode 100644
index 0000000000..5bdb9e4086
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-mac-cursors-mac-os-cursor.png differ
diff --git a/packages/mac-cursors/README.md b/packages/mac-cursors/README.md
index 798f19cc82..c80e513232 100644
--- a/packages/mac-cursors/README.md
+++ b/packages/mac-cursors/README.md
@@ -1,7 +1,18 @@
# @remotion/mac-cursors
-Internal macOS cursor components for Remotion
+Render macOS and custom CSS cursors in Remotion.
+
+[![NPM Downloads](https://img.shields.io/npm/dm/@remotion/mac-cursors.svg?style=flat&color=black&label=Downloads)](https://npmcharts.com/compare/@remotion/mac-cursors?minimal=true)
+
+## Installation
+
+```bash
+npm install @remotion/mac-cursors --save-exact
+```
+
+When installing a Remotion package, make sure to align the version of all `remotion` and `@remotion/*` packages to the same version.
+Remove the `^` character from the version number to use the exact version.
## Usage
-This is an internal package and has no documentation.
+See the [documentation](https://www.remotion.dev/docs/mac-cursors) for more information.
diff --git a/packages/mac-cursors/package.json b/packages/mac-cursors/package.json
index 3d8bb7c027..325b4f5f48 100644
--- a/packages/mac-cursors/package.json
+++ b/packages/mac-cursors/package.json
@@ -1,8 +1,7 @@
{
"name": "@remotion/mac-cursors",
"version": "4.0.512",
- "description": "Internal macOS cursor components for Remotion",
- "private": true,
+ "description": "macOS cursor components for Remotion",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"module": "dist/esm/index.mjs",
@@ -50,5 +49,9 @@
"remotion",
"macos",
"cursor"
- ]
+ ],
+ "publishConfig": {
+ "access": "public"
+ },
+ "homepage": "https://www.remotion.dev/docs/mac-cursors"
}
diff --git a/packages/studio-shared/src/package-info.ts b/packages/studio-shared/src/package-info.ts
index ee5d6b3e31..31d3355e50 100644
--- a/packages/studio-shared/src/package-info.ts
+++ b/packages/studio-shared/src/package-info.ts
@@ -251,7 +251,7 @@ export const descriptions: {[key in Pkgs]: string | null} = {
'studio-protocol':
'Create Element payloads and request installation into Remotion Studio',
'light-leaks': 'Light leak effects for Remotion',
- 'mac-cursors': 'Internal macOS cursor components for Remotion',
+ 'mac-cursors': 'macOS cursor components for Remotion',
'rough-notation': 'Rough annotation primitives for Remotion',
'player-a11y': 'Internal accessibility wrapper around @remotion/player',
starburst: 'Starburst ray effect for Remotion',
@@ -365,7 +365,10 @@ export const installableMap: {[key in Pkgs]: boolean} = {
packageName: '@remotion/light-leaks',
releaseVersion: VERSION,
}),
- 'mac-cursors': false,
+ 'mac-cursors': shouldReleasePackage({
+ packageName: '@remotion/mac-cursors',
+ releaseVersion: VERSION,
+ }),
'rough-notation': true,
starburst: shouldReleasePackage({
packageName: '@remotion/starburst',
@@ -476,7 +479,7 @@ export const apiDocs: {[key in Pkgs]: string | null} = {
design: 'https://www.remotion.dev/design',
'studio-protocol': 'https://www.remotion.dev/docs/studio-protocol',
'light-leaks': 'https://www.remotion.dev/docs/light-leaks',
- 'mac-cursors': null,
+ 'mac-cursors': 'https://www.remotion.dev/docs/mac-cursors',
'rough-notation': 'https://www.remotion.dev/docs/rough-notation',
starburst: 'https://www.remotion.dev/docs/starburst',
vercel: 'https://www.remotion.dev/docs/vercel/api',