API reference

React component syntax

The public primitives and file shape for an editable OpenSlideX presentation.

presentation.tsx

import {
  Deck,
  Slide,
  Text,
  definePresentation,
} from "@open-slidex/sdk/react";

export default definePresentation({
  title: "Quarterly update",
  component: function Presentation() {
    return (
      <Deck title="Quarterly update">
        <Slide id="slide-01" background="#F7F7F5" canvasWidth={1920} canvasHeight={1080} duration={5} fontSizeUnit="pt" theme="light">
          <Text id="slide-01-title" role="title" x={8} y={8} w={84} h={14} fontFamily="Arial" fontSize={42} fontWeight={700}>
            One clear claim
          </Text>
        </Slide>
      </Deck>
    );
  },
});

Native layer syntax

<Text id="headline" role="title" x={8} y={8} w={62} h={14} fontSize={42} fontWeight={700}>
  A clear headline
</Text>
<Image id="cover" x={70} y={8} w={22} h={40} src="assets/cover.webp" alt="Product shown on a desk" fit="cover" />
<Video id="demo" x={8} y={30} w={42} h={48} src="assets/demo.mp4" poster="assets/demo-poster.webp" />
<Shape id="accent" x={54} y={30} w={5} h={48} shape="rectangle" fill="#7C3AED" />
<Chart id="trend" x={62} y={55} w={30} h={23} type="line" data='[{"label":"Q1","value":42},{"label":"Q2","value":58}]' />
<Table id="owners" x={62} y={82} w={30} h={10} cells="Market|Owner;North|Ava" />
<Svg id="mark" x={8} y={84} w={8} h={8} src="assets/mark.svg" />
<HtmlEmbed id="imported-page" x={20} y={84} w={24} h={8} src="assets/source.html" />

Complete React API prop table

This table lists the current serializable React API fields recognized by OpenSlideX Workbench and its exporters. Shared layer fields appear once; each component page keeps its focused table too.

API	Property	Type / values	Required	Description
Shared native-layer props	id	string	Yes	Stable, unique layer identifier. Required for every visible native layer.
	x	number	Yes	Left position as a percentage of the slide canvas.
	y	number	Yes	Top position as a percentage of the slide canvas.
	w	number	Yes	Frame width as a percentage of the slide canvas.
	h	number	Yes	Frame height as a percentage of the slide canvas.
	groupId	string	—	Groups native children without adding a wrapper element.
	groupName	string	—	Human-readable name for a group in Workbench.
	sharedId	string	—	Matches the same layer type across adjacent Morph slides; unique within each slide.
	rotation	number	—	Clockwise rotation in degrees.
	opacity	number	—	Layer opacity from 0 to 1.
	motion	JSON string	—	Versioned declarative action sequence. Keep a complete static final frame.
	interaction	JSON string	—	Versioned click interaction for slide navigation or a link.
definePresentation	title	string	Yes	Presentation title. Keep it aligned with Deck title.
	component	React component	Yes	Root component that returns exactly one Deck.
defineSlideXComponent	name	string	Yes	Stable display name for the registered local component.
	component	React component	Yes	Presentation-time implementation of the component.
	props	literal prop schema	—	Optional literal string, number, and boolean prop definitions, including required.
	propsSchema	safeParse schema	—	Optional runtime schema; safeParse receives the component props.
	assetReferences	(props) => string[]	—	Optional local asset paths used by this component.
	toMotionDoc	(props) => ReactNode	—	Required when the component must expand into editable MDX or PPTX-native layers.
Deck	title	string	Yes	Deck title; a valid presentation renders one Deck root.
	children	ReactNode	Yes	One or more Slide children.
Slide	id	string	Yes	Stable slide identifier.
	background	color string	—	Slide background color.
	backgroundImage	string	—	Local background image path.
	backgroundFit	cover \| contain \| fill \| scale-down	—	How a background image fills the canvas.
	canvasWidth	number	—	Target canvas width, typically 1920.
	canvasHeight	number	—	Target canvas height, typically 1080.
	fontSizeUnit	"pt"	—	Use pt so Text and Table font sizes are points.
	duration	number	—	Slide duration in seconds.
	theme	string	—	Presentation theme tone, such as light or dark.
	slideTransition	string	—	Transition to the next slide. Use morph only with compatible sharedId pairs.
	transitionDuration	number	—	Transition duration in seconds.
	morphEasing	string	—	Easing for a Morph transition.
	morphFadeUnmatched	boolean	—	Whether unmatched layers fade during Morph.
	morphShapeSoftness	number	—	Softness for compatible shape Morph.
	morphShapePrecision	number	—	Shape sampling precision for Morph.
	morphCurveX1 / morphCurveY1 / morphCurveX2 / morphCurveY2	number	—	Control points when morphEasing is custom.
Text	children	ReactNode	Yes	Text content for the layer.
	role	"title" \| string	—	Use title for the primary slide title.
	fontFamily	string	—	Font family name.
	fontSize	number	—	Font size in points when Slide uses fontSizeUnit="pt".
	fontWeight	number \| string	—	Font weight, such as 400 or 700.
	fontStyle	"italic"	—	Italic text style.
	color	color string	—	Text color.
	background	color string	—	Text-frame background color.
	radius	number	—	Corner radius for the text frame.
	lineHeight	number	—	Line-height multiplier.
	letterSpacing	number	—	Letter spacing in points.
	textAlign	left \| center \| right	—	Horizontal text alignment.
	textVerticalAlign	top \| middle \| bottom	—	Vertical text alignment in the frame.
	listType	bullet \| ordered	—	Optional list formatting.
	listStart	number	—	Starting number for an ordered list.
Image	src	string	Yes	Portable local image path, normally under assets/.
	alt	string	—	Alternative description for the image.
	fit	cover \| contain \| fill \| scale-down	—	How image content fits its frame.
	cropX / cropY	number	—	Image translation within its frame, in percent.
	scaleX / scaleY	number	—	Image-content scale on each axis.
	radius	number	—	Frame corner radius.
	filter	string	—	Paper image-filter identifier.
	filterPreset	string	—	Preset for the selected image filter.
	filterDistortion / filterSize / filterAngle / filterContrast / filterSpeed / filterDetail	number	—	Fine controls for the selected paper filter.
Video	src	string	Yes	Local MP4/WebM path, direct URL, or supported YouTube URL.
	poster	string	—	Image shown before playback or in static rendering.
	fit	cover \| contain \| fill \| scale-down	—	How video content fits its frame.
	controls	boolean	—	Shows playback controls; defaults to true.
	loop	boolean	—	Loops playback; defaults to true.
	muted	boolean	—	Mutes and enables inline autoplay; defaults to true.
	radius	number	—	Frame corner radius.
Shape	shape	rectangle \| circle \| triangle \| diamond \| star \| line \| arrow \| chevron \| hexagon \| parallelogram	Yes	Geometry to draw.
	fill	color string	—	Interior color.
	stroke	color string	—	Outline or line color.
	strokeWidth	number	—	Outline or line width.
	radius / borderRadius	number	—	Rounded rectangle corner radius.
	corner	number	—	Continuous-corner treatment.
	points / sides	number	—	Star points or polygon sides.
	lineStyle	solid \| dashed \| dotted	—	Line stroke pattern.
	arrowStart / arrowEnd	none \| arrow \| circle \| bar	—	Line endpoint decorations.
	arrowStartSize / arrowEndSize	number	—	Endpoint size as a percentage.
	shapeImageSrc	string	—	Optional image clipped inside a non-line shape.
	shapeImageAlt	string	—	Description for the shape image.
	shapeImageFit	cover \| contain \| fill \| scale-down	—	How the shape image fills its geometry.
	shapeImageCropX / shapeImageCropY / shapeImageScaleX / shapeImageScaleY	number	—	Shape-image crop and scale controls.
	mask	none \| alpha \| luma \| clip	—	Shape mask mode.
	operation	none \| subtract \| intersect \| exclude	—	Shape boolean treatment.
Chart	type	bar \| line \| area \| pie \| donut \| scatter	Yes	Chart visualization type.
	data	JSON string	Yes	One to 24 rows; every row needs a finite numeric value and may include label, x, size, and color.
	chartDataByType	JSON string	—	Optional data sets keyed by chart type.
	chartPreset	executive \| minimal \| vivid	—	Visual preset.
	chartTheme	light \| dark-gold	—	Chart-specific theme.
	palette	aurora \| editorial \| gilded \| ocean \| sunset	—	Named color palette.
	colorMode	palette \| single \| emphasis \| gradient	—	Color distribution strategy.
	emphasisIndex	number	—	Data point emphasized by color mode.
	annotationIndex / annotationText / annotationColor	number \| string	—	Optional annotation target, label, and color.
	barGap	compact \| balanced \| airy	—	Spacing for bar charts.
	barRadius / areaOpacity / donutHole	number	—	Rounded bars, area fill opacity, or donut hole size.
	lineSmooth	boolean	—	Smoothes a line or area path.
	showAxes / showGrid / showLabels	boolean	—	Shows axes, grid, or labels.
	labelMode / labelColor	all \| value \| category \| none \| color	—	Label visibility mode and color.
	numberFormat	auto \| integer \| decimal \| percent \| currency \| compact	—	Value formatting.
	decimals / currency	number \| string	—	Decimal places and currency code or symbol.
	sort	input \| ascending \| descending	—	Data ordering.
	referenceValue / referenceLabel / referenceColor	number \| string	—	Optional reference line value, label, and color.
	chartMotion	auto \| grow \| draw \| sweep \| pop \| none	—	Chart entrance motion.
Table	cells	string	Yes	Cell data: pipes separate columns and semicolons separate rows.
	rows	number	—	Number of rows, from 1 through 50.
	columns / cols	number	—	Number of columns, from 1 through 50.
	columnLabels / rowLabels	string	—	Serialized labels for columns or rows.
	columnWidths / rowHeights	string	—	Serialized fractional track sizes.
	cellOverrides	JSON string	—	Per-cell visual overrides created by Workbench.
	fontFamily / fontSize / fontWeight	string \| number	—	Table type styling; fontSize is in points.
	color / textColor	color string	—	Table text color.
	background / backgroundColor / bg	color string	—	Table background color.
	cellBackground / stripeBackground	color string	—	Cell fill and alternating-row fill.
	borderColor / borderWidth / borderStyle	color \| number \| solid \| dashed \| dotted	—	Table border styling.
	textAlign / textVerticalAlign	left \| center \| right / top \| middle \| bottom	—	Cell alignment.
	cellPaddingX / cellPaddingY	number	—	Horizontal and vertical cell padding in pixels.
Svg	src	string	Yes	Script-free local SVG asset path.
	stage	number	—	SVG animation stage index.
	stageDuration	number	—	SVG stage duration in seconds.
	easing	string	—	Easing for the SVG stage.
	sharedScene	string	—	Optional scene key shared across slides.
HtmlEmbed	src	string	Yes	Controlled local HTML asset path.
	page	number	—	HTML presentation page to show; starts at 1.
	sharedScene	string	—	Optional scene key shared across slides.

Start with one valid document

Default-export definePresentation({ title, component }). The component must render one Deck with a matching title and one or more Slide children. Import public primitives only from @open-slidex/sdk/react.

Deck and Slide establish the document; Text, Image, Video, Svg, Chart, Table, Shape, and HtmlEmbed create native layers. Do not write internal names such as ImageBlock or SvgBlock in React source.

Use literal frames

Every visible native layer needs a stable, unique id plus literal x, y, w, and h values. These are percentages of the slide canvas. Text fontSize values use points when the Slide sets fontSizeUnit="pt".

Use literal, serializable values when a property should be visible and editable in Canvas or Inspector. Computed expressions, loops, spreads, hooks, and conditions remain code-only and are not guaranteed to round-trip through visual editing.

Keep the sandbox portable

Use verified relative assets under the deck's assets/ directory. HtmlEmbed accepts controlled, imported local HTML; Svg accepts script-free local SVG. Do not use absolute paths, Base64 or blob URLs, arbitrary HTML, event handlers, network calls, Node APIs, or external npm imports.

Card, Metric, Stack, Group, Title, Icon, and Notes are not supported React primitives. Use the native layers above instead.