@wix/site-service-tabbing

Keyboard Tab focus trap for modals and dialogs. Traps Tab navigation within one or more component containers, and releases it on close. Accessibility category.

Install

yarn add @wix/site-service-tabbing

Usage

import { TabbingDefinition } from '@wix/site-service-tabbing/definition'
import { TabbingService } from '@wix/site-service-tabbing/implementations'

createServicesMap().addService(TabbingDefinition, TabbingService, { screenReaderFocus: true })

const tabbing = servicesManager.getService(TabbingDefinition)

// When a modal opens — trap Tab within #my-modal:
tabbing.setParentComponents(['my-modal'])

// When it closes — release the trap, returning tabbing to the whole page:
tabbing.reset()

This service depends on @wix/site-service-rendering-context being registered in the same services map — it reads SSR from it to no-op during server-side rendering.

API

| Member | Type | Description | |---|---|---| | setParentComponents | (parentCompIds: string[]) => void | Traps Tab navigation within the given container(s): every focusable element outside them gets tabindex="-1" (prior value saved to data-restore-tabindex, plus aria-hidden="true" if screenReaderFocus). Any currently active trap is released first, then the new one is applied. No-op during SSR. | | reset | () => void | Releases the trap entirely: restores saved tabindex values (removing the attribute where there was none) and clears data-restore-tabindex / aria-hidden, returning tabbing to the whole page (page root). No-op during SSR. |

Both are plain methods — this service exposes no property getters.

Configuration

ITabbingServiceConfig:

export type ITabbingServiceConfig = {
    screenReaderFocus?: boolean
}

• screenReaderFocus — when true, trapped (outside) elements also receive aria-hidden="true" so screen readers skip them. Read once at construction.

SSR state is not configured here — it is resolved from @wix/site-service-rendering-context at construction.

Reactivity

None. This service holds no reactive state — it performs imperative DOM mutations, restoring tabindexes from the data-restore-tabindex attributes it stamps. There are no signals and no _updateConfig.