@microsoft/fabric-visuals-extensibility
v5.3.0
Published
Extensibility components for Fabric Apps - Analytics
Readme
@microsoft/fabric-visuals-extensibility
Extensibility components for Fabric Apps - Analytics.
VisualContainer
Wraps any children in a div with a card background and border, an optional
title/subtitle header, an optional hover/focus-revealed action toolbar, and a
right-click actions menu.
import { VisualContainer } from '@microsoft/fabric-visuals-extensibility';
import type { BuiltInActions, VisualContainerAction } from '@microsoft/fabric-visuals-extensibility';
const refreshAction: VisualContainerAction = {
id: 'refresh',
label: 'Refresh',
icon: <RefreshIcon />,
onClick: () => reload(),
};
function Example() {
return (
<VisualContainer
header={{ title: 'Sales overview', subtitle: 'Last 12 months' }}
builtInActions={{ copyVisual: {} }}
customActions={[refreshAction]}
>
<MyVisual />
</VisualContainer>
);
}Props
| Prop | Type | Description |
| --- | --- | --- |
| children | ReactNode | Content rendered in the container body. |
| header | VisualContainerHeader | A structured title/subtitle or custom header content. |
| builtInActions | BuiltInActions | Built-in actions to render before custom actions. |
| customActions | VisualContainerAction[] | Consumer-defined toolbar actions. |
| maxVisibleButtons | number | Maximum inline buttons before overflow. Defaults to 2; values below 1 are clamped to 1. |
| rootClassName | string | CSS class merged onto the outermost element for grid/flex placement, margins and whole-container sizing. |
| className | string | CSS class merged onto the inner card surface for background, border, radius and padding, not outer layout. |
Actions
With a header, actions appear beside the title. Without a header, they appear in a floating toolbar. Extra actions move into an overflow menu according to maxVisibleButtons.
Right-clicking the container opens the same visible actions in a context menu. When there are no visible actions, the browser context menu is left unchanged.
Pass VisualContainerAction objects through customActions to add application-specific custom actions. Custom actions render after built-in actions.
The built-in actions are copyVisual and viewAsTable. Built-in actions are opt-in when using VisualContainer directly:
<VisualContainer builtInActions={{
copyVisual: {},
}}>
<MyVisual />
</VisualContainer>Show as table
viewAsTable is an accessibility option that renders the visual's data as an
accessible HTML table in a modal popup over a dimmed backdrop. It always lives in the
overflow menu (never an inline button), and it is hidden unless a table data source is
available, so a container with no data never shows a dead entry.
Supply a tableSource provider in viewAsTable. It returns VisualTable[]
or null (optionally async) when the popup opens. A null result shows the empty
state message; thrown errors or rejected promises show the error state message. Keep the provider
stable to avoid reloading an open dialog on unrelated rerenders. Self-framing VegaVisual supplies its provider
automatically; a hand-authored VisualContainer must supply its own:
function Example() {
const provideTables = useCallback(() => buildTables(), []);
const actions = useMemo<BuiltInActions>(() => ({
viewAsTable: { tableSource: provideTables },
}), [provideTables]);
return (
<VisualContainer builtInActions={actions}>
<MyVisual />
</VisualContainer>
);
}VegaVisual uses the compiler's resolved source tables: the explicit data prop
takes precedence over eligible top-level inline object rows. These tables retain
their original rows and columns before Vega transforms or aggregation.
Each table is first capped at MAX_TABLE_ROWS (3,000) source rows and
MAX_TABLE_COLUMNS (100) source columns. Within that window, columns containing
only null, missing values, empty strings, or whitespace-only strings are omitted.
Values such as 0 and false keep a column visible. Removed columns are not
replaced by later source columns, and values beyond the row limit do not keep a
column visible. Tables with no rows retain their capped headers; tables with no
populated columns show the empty state.
The dialog title's accessible name includes the first table's row and column counts, announcing "n of m rows" or "n of m columns" when truncated, without changing the visible title. Shown column counts exclude omitted empty columns; when columns are truncated, the total is the original source schema's column count. When a visual produces several tables, the first table uses the dialog title and each subsequent table has its own count-aware heading.
Keyboard navigation
Keyboard navigation has separate container, content, and toolbar modes. Tab moves between containers; Enter enters the current visual's content. Alt+Shift+F10 moves to the first enabled toolbar action. Within the toolbar, Tab/Shift+Tab and Left/Right arrows both cycle and wrap among enabled actions, including More actions. Escape returns to the current container; toolbar buttons are not ordinary Tab stops outside toolbar mode. In the overflow menu, Up/Down arrows wrap among enabled items, and Escape first closes the menu and restores its trigger.
Copying and capturing
Use the highest-level API that fits the caller:
| Goal | API |
| --- | --- |
| Show the standard Copy button | builtInActions={{ copyVisual: {} }} |
| Copy from application code | VisualContainerHandle.copyImageToClipboard() |
| Capture the container without copying | VisualContainerHandle.captureAsImage() |
| Capture or copy an element without a container | captureElementAsImage() and writeImageToClipboard() |
interface VisualContainerHandle {
/** Inner card surface and capture target, not the outer layout root. */
element: HTMLElement | null;
captureAsImage(): Promise<Blob>;
copyImageToClipboard(): Promise<void>;
}The built-in Copy action captures an opaque PNG without container actions and writes image and HTML clipboard representations. A structured header contributes the title; the container supplies a localized copy time. A plain-text caption is included only when the title is nonblank, so clients that prefer plain text cannot paste just the timestamp. It also reports success or failure through the shared Toast component.
Clipboard writes require a secure context and a user gesture. Cross-origin iframe hosts must also grant allow="clipboard-write".
For a bare element without a VisualContainer:
import { useRef } from 'react';
import {
captureElementAsImage,
writeImageToClipboard,
} from '@microsoft/fabric-visuals-extensibility';
const elementRef = useRef<HTMLDivElement>(null);
async function copyChart() {
if (!elementRef.current) {
return;
}
const image = await captureElementAsImage(elementRef.current);
await writeImageToClipboard(image, {
title: 'Revenue',
timestamp: new Date().toLocaleString(),
});
}CopyVisualCaption accepts optional, already-formatted title and timestamp strings. Timestamp-only captions are included in HTML, not plain text; omitting the caption writes only the image. Add the exported CAPTURE_EXCLUDE_ATTR attribute to descendants that should be omitted from a capture.
Styling
The container uses the design tokens from @microsoft/fabric-visuals-core. className targets the themed card that owns the background, border, radius, and padding; it does not target the header, body, or toolbar.
Use rootClassName for placement and whole-container sizing without adding a wrapper. For self-framing VegaVisual and DataGrid, the equivalent props are containerRootClassName for layout and containerClassName for the card. Give virtualized grids a definite height rather than only a minimum height.
Toast notifications
Use Toast and useToast for custom-action or any other notifications with the same styling as built-in Copy. No VisualContainer or provider is required.
import { Toast, useToast } from '@microsoft/fabric-visuals-extensibility';
function NotificationExample() {
const { toast, showToast, dismissToast } = useToast();
const notify = () => showToast({ tone: 'success', title: 'Action completed' });
return (
<>
<button type="button" onClick={notify}>Show notification</button>
{toast && <Toast toast={toast} onDismiss={dismissToast} />}
</>
);
}showToast accepts a tone ('success' or 'error'), a localized title, and an optional description. Success toasts dismiss after 4 seconds; errors after 10 seconds. Each hook replaces its previous toast, while independent hooks share one viewport stack.
