🔧 Volto widgets

sc-videos registers several Volto widgets for editing and displaying video-related fields.

✏️ VideoURLWidget (edit)

The primary widget for entering video URLs and fetching metadata. Used both in the content type's sidebar form and inside the Video Player block's in-block 🧱 Blocks and widgets.

Registration: config.widgets.widget.VideoURL Module: components/Widgets/VideoURLWidget.tsx Storybook: Widgets/VideoURL/Edit

Props

Prop	Type	Required	Description
id	string	Yes	Field name (for example, videoUrl).
title	string	Yes	Field label.
description	string	No	Help text shown below the field.
value	string	No	Current URL value.
formData	Record<string, unknown>	No	Parent form data. Used to read _metadata for the preview.
onChange	(id: string, value: unknown) => void	Yes	Called on every keystroke and by applyVideoMetadataToForm.
onBlur	(id: string, value: string | undefined) => void	Yes	Called when the input loses focus.
onClick	() => void	Yes	Called when the input is clicked.
placeholder	string	No	Input placeholder text.
isDisabled	boolean	No	Disable the input.
required	boolean	No	Mark the field as required.
error	string[]	No	Validation error messages.

Behavior

1. Typing: updates the field value on every keystroke via onChange.

2. Arrow button (→). triggers fetchVideoMetadata(), which calls the 🌐 REST API. @video-metadata and then runs applyVideoMetadataToForm() to populate sibling fields (title, description, duration, etc.).

3. Clear button (✕). resets the URL and clears _metadata.

4. Metadata preview: when _metadata is populated, shows a thumbnail, channel, and duration below the input.

5. Multi-instance sync: a useEffect re-syncs local state with props.value so multiple instances of the widget (for example, in-block EditForm + content sidebar) stay consistent.

Metadata population

When the arrow button is clicked and metadata is fetched successfully, applyVideoMetadataToForm() writes to these sibling fields (only if currently empty):

Form field	Metadata source	Transform
title	metadata.title	.
description	metadata.text	Truncated per voltoVideos.description settings (default: 150 chars with ... ellipsis). See ⚙️ Configuration.
duration	metadata.duration	.
channel	metadata.channel	.
subjects	metadata.subjects	.
video_id	metadata.video_id	.
service	metadata.service	.
_metadata	full metadata object	Always written

👁️ VideoURLWidgetView (view)

Read-only display of a video URL as a clickable link.

Registration: config.widgets.views.widget.VideoURL Module: components/Widgets/VideoURLWidgetView.tsx Storybook: Widgets/VideoURL/View

Props

Prop	Type	Required	Description
value	string	No	The URL to display.
children	ReactNode	No	Custom render function.
className	string	No	CSS class name.

🔒 VideoMetadataWidget (edit)

A hidden widget that stores the raw metadata JSON in form state. Renders no visible UI. purely a data-storage mechanism.

Registration: config.widgets.widget.VideoMetadata Module: components/Widgets/VideoMetadataWidget.tsx Storybook: Widgets/VideoMetadata/Edit

👁️ VideoMetadataWidgetView (view)

View-mode counterpart of VideoMetadataWidget. Also renders nothing. consumed programmatically.

Registration: config.widgets.views.widget.VideoMetadata

🔍 VideoInput

An in-block placeholder component for picking existing Video content. Used by the Video block when no video is selected.

Module: components/Widgets/VideoInput.tsx Storybook: Widgets/VideoInput/Edit

Props

Prop	Type	Required	Description
id	string	No	Block or field ID.
block	string	No	Block ID (used by withObjectBrowser).
description	string	No	Custom placeholder text.
selected	boolean	No	Whether the host block is currently selected.
onFocus	() => void	No	Called when the placeholder is clicked.
onSelectItem	(url: string, item: Record<string, any>) => void	Yes	Called when a Video is picked from the object browser.

Behavior

1. Renders a camera icon, descriptive text, and a browse button.

2. Clicking the browse button opens the Volto object browser with:

   • mode: 'link'

   • searchableTypes: ['Video']

   • selectableTypes: ['Video']

3. On selection, calls onSelectItem with the item's URL and full catalog metadata.

4. The hosting block's dataAdapter is responsible for committing the selection to block data.

Wrapped with the withObjectBrowser HOC so it manages its own object browser popup state.

See also

• 🧱 Volto blocks. How these widgets are used within the blocks.

• 🧱 Blocks and widgets. Architectural overview of the widget/block relationship.