Skip to main content

StartOptions

Options for starting the Virtual Screen Reader.

For example, to use the Virtual Screen Reader against the entire page:

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start Virtual on the entire page.
  await virtual.start({ container: document.body });

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

To instead use the Virtual Screen Reader within a particular element (with that element included):

import { virtual } from "@guidepup/virtual-screen-reader";
import { screen } from "@testing-library/dom";

test("example test", async () => {
  const container = screen.getByRole("navigation");

  // Start Virtual within a <nav> element in the page.
  await virtual.start({ container });

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

If using in a headed browser environment such as Storybook, you can also opt-in to having the virtual cursor displayed visually:

import { virtual } from "@guidepup/virtual-screen-reader";

test("example test", async () => {
  // Start Virtual on the entire page with the virtual cursor displayed visually.
  await virtual.start({ container: document.body, displayCursor: true });

  // Stop the Virtual Screen Reader.
  await virtual.stop();
});

Contents:

startOptions.container​

The bounding HTML element to use the Virtual Screen Reader in.

To use the entire page pass document.body.

Type: HTMLElement

startOptions.window​

Optional: The window instance.

Only required if the window instance is not already globally available. For example, when you are in a Node environment and using a custom DOM implementation that is not attached to the global scope.

Defaults to using the global window instance.

Type: Window

startOptions.displayCursor​

Optional: Display the Virtual Screen Reader cursor visually on the target element.

Note: There is a performance overhead to visually rendering the cursor.

Type: boolean