Skip to main content

react-components-v2-accessibility

title: "Breaking: React component accessibility and tooltip updates" date: 2026-05-13 tags:

  • improved

@trackunit/react-components and @trackunit/react-form-components include breaking accessibility, tooltip, and layout updates for component consumers. These changes were made to improve accessibility compliance and create more consistent tooltip and labeling behavior across components

Breaking Changes​

  • IconButton: Icon buttons must now have an accessible name. Pass either title or ariaLabel.

    • title renders the component-library tooltip and is used as the accessible name unless ariaLabel is also provided.
    • ariaLabel lets the accessible name differ from the visible tooltip text.
    • title is no longer rendered as a native DOM title attribute, so tests should query the button by role/name instead of getByTitle.
    • icon must be an <Icon /> element from @trackunit/react-components; arbitrary ReactNode icons are no longer accepted.
    • Disabled and loading icon buttons do not show the tooltip.
    • The <Icon /> passed via icon is automatically marked aria-hidden so the button's accessible name is the only label announced.
    <IconButton icon={<Icon name="Trash" size="small" />} title="Delete item" />
    <IconButton ariaLabel="Delete asset" icon={<Icon name="Trash" size="small" />} title="Delete" />

  • CardHeader: Removed the deprecated onClickClose prop and the built-in close button. Render close actions through actions instead.

    <CardHeader
      actions={
        <IconButton icon={<Icon name="XMark" size="small" />} onClick={onClose} title="Close" variant="ghost-neutral" />
      }
      heading="Details"
    />

  • Breadcrumb: The previously proposed backButtonTitle and expandCollapsedItemsTitle props are no longer accepted on Breadcrumb, BreadcrumbContainer, or BreadcrumbForMediumScreen. The back button and the medium-screen ellipsis button now resolve their accessible names from the react-components library translations (breadcrumb.backButton and breadcrumb.expandButton). Host applications must register the react-components library translations to get the localized strings. Consumers that were forwarding these props should remove them from their JSX.

    <Breadcrumb breadcrumbItems={items} onClickBack={onBack} />

  • Pagination: previousPageTitle and nextPageTitle are now required and are passed to the previous/next IconButtons.

    <Pagination
      nextPage={nextPage}
      nextPageTitle="Next page"
      previousPage={previousPage}
      previousPageTitle="Previous page"
      pageCount={pageCount}
    />

  • Tag: Dismissible tags now require removeTagLabel whenever onClickClose is provided. The close icon uses that label for its tooltip.

    <Tag onClickClose={onRemove} removeTagLabel="Remove tag">
      Active filter
    </Tag>

  • KPI: Removed the tooltipLabel prop and the built-in tooltip wrapper from KPI. Wrap KPI with Tooltip yourself or use KPICard when the tooltip belongs to a card KPI.

    <Tooltip label="Average utilization across all assets" placement="bottom">
      <KPI title="Utilization" unit="%" value={87} />
    </Tooltip>

  • KPICard: tooltipLabel now belongs to KPICard instead of being forwarded to KPI. When provided, the tooltip wraps the card body rather than only the inner KPI.

    <KPICard tooltipLabel="Average utilization across all assets" title="Utilization" unit="%" value={87} />

  • Notice: Removed withTooltip and tooltipLabel. Notice no longer renders a tooltip internally because notices are not intended to be interactive or rely on hover behavior. Wrap it in Tooltip where hover help is still needed. .

    <Tooltip label="Battery level is below 20%" placement="bottom">
      <Notice color="warning" iconName="ExclamationTriangle" label="Low battery" />
    </Tooltip>

  • ToggleGroup: Icon-only mode is now a stricter discriminated union, and per-item styling has been tightened.

    • When isIconOnly is true, every list item must provide tooltip.content because the tooltip is the button's only accessible name.
    • Non-icon-only groups should omit isIconOnly or pass false; item tooltip content remains optional.
    • List items no longer accept a style prop (BasicToggleGroupListProps no longer extends Styleable). Apply per-item styling through className or wrap the group instead.
    <ToggleGroup
      isIconOnly
      list={[
        { id: "list", title: "List", iconName: "Bars3", tooltip: { content: "Show list view" } },
        { id: "map", title: "Map", iconName: "MapPin", tooltip: { content: "Show map view" } },
      ]}
      selected={selected}
      setSelected={setSelected}
    />

  • ActionButton (@trackunit/react-form-components): title is now a required prop and is forwarded to the inner IconButton for the tooltip and accessible name. The inherited optional title from ButtonCommonProps has been omitted to enforce this.

    <ActionButton type="COPY" title="Copy value" value={inputRef} />

  • OptionCard (@trackunit/react-form-components): Container layout changed from display: contents to flex grow-0. Layouts that relied on the card collapsing into its parent's grid or flex flow may need a wrapping flex container.

  • HorizontalOverflowScroller: The internal overflow indicator IconButtons no longer expose scroll-button tooltips and are rendered disabled. Consumers should not rely on the old hover tooltip or clickable indicator-button behavior.

Codemods​

This release ships automated codemods for breaking changes in @trackunit/react-components@2.0.0 and @trackunit/react-form-components@2.0.0, orchestrated by the @trackunit/migrations coordinator (modeled after nx migrate).

Running the codemods​

Run the two-step flow from your project root:

1. Bump @trackunit/* versions in package.json and collect pending

migrations into trackunit-migrations.json

nx g @trackunit/migrations:migrate

2. Review trackunit-migrations.json, then execute the pending migrations

nx g @trackunit/migrations:run-migrations

Previously-applied migrations are tracked in trackunit-migrations.json and will not re-run.

Included migrations

@trackunit/react-components@2.0.0

  • v2-0-0-iconbutton-add-required-name — Adds a placeholder title prop to IconButton usages missing both title and ariaLabel (now required for accessibility).
  • v2-0-0-breadcrumb-remove-deprecated-props — Removes the deprecated backButtonTitle and expandCollapsedItemsTitle props from Breadcrumb, BreadcrumbContainer, and BreadcrumbForMediumScreen.
  • v2-0-0-cardheader-onclickclose-to-actions — Replaces the removed CardHeader.onClickClose prop with an actions slot containing an IconButton + XMark icon.
  • v2-0-0-pagination-add-required-titles — Adds the now-required previousPageTitle and nextPageTitle props to Pagination.
  • v2-0-0-tag-add-removetaglabel — Adds the now-required removeTagLabel prop to dismissible Tag usages (those with onClickClose).
  • v2-0-0-kpi-tooltiplabel-to-wrapper — Replaces the removed KPI.tooltipLabel prop with a Tooltip wrapper around the KPI.
  • v2-0-0-notice-tooltiplabel-to-wrapper — Replaces the removed Notice.withTooltip / Notice.tooltipLabel props with a Tooltip wrapper.
  • v2-0-0-togglegroup-remove-item-style — Removes the no-longer-supported style property from inline ToggleGroup list items.

@trackunit/react-form-components@2.0.0

  • v2-0-0-actionbutton-add-title — Adds the now-required title prop to ActionButton, defaulting to a sensible English string per action type.