> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: LiveRegion Component

## Article: LiveRegion Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/feedback/live-region-component.md

## Article Content:

# LiveRegion

_Components/Feedback_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/liveregion>

## Overview

```jsx
() => {
  const ref = React.useRef(null);

  const onButtonClick = () => {
    ref.current.broadcast({ message: 'This is a message' });
  };

  return (
    <StorybookComponents.Stack>
      <LiveRegion ref={ref} />
      <Button onClick={onButtonClick}>Broadcast</Button>
    </StorybookComponents.Stack>
  );
};
```

Live region is a mechanism that broadcasts a message for screen reader users to inform them about the change in the page layout or the status.

### Do

- Use it to inform users with visual impairments about change in page content
- Use it to inform users with visual impairments about page status change without moving users' focus

### Don't

- Don't use it when triggered action moves user focus to another element, for example to a newly created item. Use `<LiveRegion/>` when user focus remains where it is, but users must be aware of the changes that happened on the page.
- Don't use it to announce the opening of menus, modals or notifications. These types of announcements are a built-in definition of components.
- Don't use it to announce dynamic content that's not critical. Avoid adding unnecessary noise for assistive technologies.

### Feature examples

#### Broadcast

Specify a message to announce for screen reader users with `broadcast` prop.

```jsx
() => {
  const ref = React.useRef(null);

  const onButtonClick = () => {
    ref.current.broadcast({ message: 'This is a message' });
  };

  return (
    <StorybookComponents.Stack>
      <LiveRegion ref={ref} />
      <Button onClick={onButtonClick}>Broadcast</Button>
    </StorybookComponents.Stack>
  );
};
```

#### Role

Specify how urgently a message should be broadcasted with `role` prop.

There are 2 roles types:

- `status` (default) - use it when it's important that user receives updates about changes in the region, but not so rapidly that natural flow would be interrupted. Screen reader will announce a message after the current message is delivered.
- `alert` - use for time sensitive and critical notifications that require immediate users attention. Message will be announced right away, even if screen reader is currently in the middle of a sentence. As such, it can be disruptive and should be **used sparingly**.

```jsx
() => {
  const ref = React.useRef(null);

  const onButtonClick = (role) => {
    const message =
      role === 'alert'
        ? 'This is an alert message'
        : 'This is a status message';

    ref.current.broadcast({ message, role });
  };

  return (
    <StorybookComponents.Stack>
      <LiveRegion ref={ref} />
      <Button onClick={() => onButtonClick('alert')}>
        Broadcast alert message
      </Button>
      <Button onClick={() => onButtonClick('status')}>
        Broadcast status message
      </Button>
    </StorybookComponents.Stack>
  );
};
```

### Common use case examples

#### Remove item

Use `live region` to inform screen reader users about items removed from the page.

```jsx
() => {
  const liveRef = React.useRef(null);
  const addBtnRef = React.useRef(null);
  const inputRef = React.useRef([]);
  const [rows, setRows] = React.useState([
    { id: 1, value: '' },
    { id: 2, value: '' },
  ]);
  const [mounted, setMounted] = React.useState(false);
  const [itemAdded, setItemAdded] = React.useState(false);

  const removeItem = (idToRemove, index) => {
    if (rows.length === 1) {
      addBtnRef.current.focus();
    } else {
      const indexToFocus = index === 0 ? 1 : index - 1;
      inputRef.current[indexToFocus].focus();
    }
    setRows(rows.filter(({ id }) => id !== idToRemove));
    liveRef.current.broadcast({ message: 'Item deleted' });
  };

  const addItem = () => {
    setRows([...rows, { id: new Date().getTime(), value: '' }]);
    liveRef.current.broadcast({ message: 'Item Added' });
    setItemAdded(true);
  };

  React.useEffect(() => {
    if (itemAdded) {
      inputRef.current[inputRef.current.length - 1].focus();
      setItemAdded(false);
    }
  }, [itemAdded]);

  React.useEffect(() => {
    inputRef.current = inputRef.current.slice(0, rows.length);
  }, [inputRef.current]);

  return (
    <Box direction="vertical" gap="SP3">
      <LiveRegion ref={liveRef} />
      {rows.map((row, index) => (
        <Box key={row.id} gap="SP2">
          <Box width="100%" direction="vertical">
            <Input
              ref={(el) => {
                inputRef.current[index] = el;
              }}
              value={row.value}
              placeholder="e.g., Unlimited yoga classes"
            />
          </Box>
          <IconButton skin="inverted" onClick={() => removeItem(row.id, index)}>
            <Icons.Delete />
          </IconButton>
        </Box>
      ))}

      <TextButton ref={addBtnRef} onClick={addItem} prefixIcon={<Icons.Add />}>
        Add Item
      </TextButton>
    </Box>
  );
};
```

#### Duplicate item

Use `live region` to inform screen reader users about duplicated items added to the page.

```jsx
() => {
  const ref = React.useRef(null);
  const inputRef = React.useRef([]);
  const [rows, setRows] = React.useState([
    { id: 1, value: '' },
    { id: 2, value: '' },
  ]);
  const [mounted, setMounted] = React.useState(false);

  const duplicateItem = (index) => {
    setRows([...rows, { id: new Date().getTime(), value: rows[index].value }]);
    inputRef.current = inputRef.current.slice(0, rows.length);
    ref.current.broadcast({ message: 'Item duplicated', role: 'status' });
  };

  const handleOnChange = (index, value) => {
    const updatedRows = rows.map((row, i) =>
      index === i ? { ...row, value } : row,
    );
    setRows(updatedRows);
  };

  React.useEffect(() => {
    if (!mounted) {
      setMounted(true);
      return;
    }

    inputRef.current[rows.length - 1].focus();
  }, [inputRef.current]);

  return (
    <Box direction="vertical" gap="SP3">
      <LiveRegion ref={ref} />
      {rows.map((row, index) => (
        <Box gap="SP2">
          <Box width="100%" direction="vertical">
            <Input
              value={row.value}
              ref={(el) => {
                inputRef.current[index] = el;
              }}
              placeholder="e.g., Unlimited yoga classes"
              onChange={(e) => {
                handleOnChange(index, e.target.value);
              }}
            />
          </Box>
          <IconButton skin="inverted" onClick={() => duplicateItem(index)}>
            <Icons.Duplicate />
          </IconButton>
        </Box>
      ))}
    </Box>
  );
};
```

#### Filter Table

Use `live region` to inform users about the number of items that match their filter criteria.

```jsx
() => {
  const liveRef = React.useRef(null);

  const [selectedOption, setSelectedOption] = React.useState(0);

  const data = [
    {
      name: `Light grey hoodie`,
      SKU: '00224239',
      price: '$59.00',
      inventory: 'In stock',
      collection: '2021 Winter',
    },
    {
      name: `Black watch`,
      SKU: '00352464',
      price: '$229.00',
      inventory: 'In stock',
      collection: '2021 Summer',
    },
    {
      name: 'Reading glasses',
      SKU: '00486430',
      price: '$69.00',
      inventory: 'In stock',
      collection: '2021 Autumn',
    },
    {
      name: 'Leather shoes',
      SKU: '00515642',
      price: '$129.00',
      inventory: 'Out of stock',
      collection: '2021 Winter',
    },
    {
      name: 'Leather shoes',
      SKU: '00515642',
      price: '$129.00',
      inventory: 'Out of stock',
      collection: '2021 Spring',
    },
  ];

  const [records, setRecords] = React.useState(data);

  const columns = [
    { title: 'Name', render: (row) => row.name },
    { title: 'SKU', render: (row) => row.SKU },
    { title: 'Inventory', render: (row) => row.inventory },
    { title: 'Collection', render: (row) => row.collection },
    { title: 'Price', render: (row) => row.price },
  ];

  const handleSelection = (option) => {
    setSelectedOption(option.id);
    const filteredData =
      option.value === 'All Collections'
        ? data
        : data.filter((item) => item.collection === option.value);
    setRecords(filteredData);

    const numOfItemsFound = filteredData.length;
    liveRef.current.broadcast({
      message: `${numOfItemsFound} ${
        numOfItemsFound > 1 ? 'items' : 'item'
      } found`,
      role: 'status',
    });
  };

  return (
    <Card hideOverflow>
      <LiveRegion ref={liveRef} />
      <Table data={records} columns={columns} rowVerticalPadding="medium">
        <TableToolbar>
          <TableToolbar.ItemGroup position="start">
            <TableToolbar.Item>
              <FormField label="Filter by">
                <Dropdown
                  options={[
                    { id: 0, value: 'All Collections' },
                    { id: 1, value: '2021 Winter' },
                    { id: 2, value: '2021 Autumn' },
                    { id: 3, value: '2021 Summer' },
                    { id: 4, value: '2021 Spring' },
                  ]}
                  selectedId={selectedOption}
                  border="round"
                  size="small"
                  popoverProps={{ appendTo: 'window' }}
                  onSelect={handleSelection}
                  valueParser={({ value }) => value}
                />
              </FormField>
            </TableToolbar.Item>
          </TableToolbar.ItemGroup>
        </TableToolbar>
        <Table.Content />
      </Table>
    </Card>
  );
};
```

## Code

```jsx
import { LiveRegion } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `ref` | `null \| string \| (instance: LiveRegionRefType \| null) => void \| RefObject<LiveRegionRefType>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { LiveRegionUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { LiveRegionTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { LiveRegionTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { LiveRegionTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `exists` | Checks whether the component found with the given data hook |
| `element` | Gets the component root element |
| `getMessage` | Returns the message |
| `getRole` | Returns the role |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.320.0** (2026-09-03) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.119.0** (2024-07-31) — fix: adjusting position so it wouldn't affect layout ([#14002](invalid-url))
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.104.1** (2024-05-14) — maintenance release, no component-specific changes
- **1.101.0** (2024-04-12) — fix: reverting LiveRegion NVDA screen reader regression ([#13545](invalid-url))
- **1.98.0** (2024-03-15) — maintenance release, no component-specific changes
- **1.97.2** (2024-03-04) — fix: live region now supports announcing same message multiple times ([#13406](invalid-url))
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes