---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
  - property: og:type
    content: article
  - property: article:section
    content: Платформа плагинов
  - property: og:title
    content: API Reference - plugin-sdk-react
  - property: article:tag
    content: Техническая инструкция
alternate:
  - https://yandex.ru/support/tracker/en/plugins/tools/sdk/react.md
  - https://yandex.ru/support/tracker/ru/plugins/tools/sdk/react.md
  - href: en/plugins/tools/sdk/react.md
    type: text/markdown
    title: Markdown version
  - href: ../../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/tracker/en/llms.txt


# API Reference - @weavix/sdk-react

## Components {#components}

### TrackerPluginProvider {#tracker-plugin-provider}

A provider for initializing the Tracker plugin. Wraps the application and manages the plugin's lifecycle. Provides the theme, language, and slot context via React context.

**Props:** [`TrackerPluginProviderProps`](#trackerpluginproviderprops)

#### Features {#tracker-plugin-provider-features}

- Automatic plugin initialization
- Loading and error state management
- Provides context via the React Context API
- Automatically notifies the host when the plugin is ready
- Protection from double initialization in React StrictMode

#### Example (basic usage) {#tracker-plugin-provider-example-basic}

```tsx
import { TrackerPluginProvider } from '@weavix/sdk-react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

const root = createRoot(document.getElementById('root')!);

root.render(
  <TrackerPluginProvider>
    <App />
  </TrackerPluginProvider>,
);
```

#### Example (with custom options) {#tracker-plugin-provider-example-custom-options}

```tsx
import { TrackerPluginProvider } from '@weavix/sdk-react';
import { Loader } from './components/Loader';
import { ErrorScreen } from './components/ErrorScreen';

root.render(
  <TrackerPluginProvider
    autoResize={false}
    fallback={<Loader />}
    errorFallback={(error) => <ErrorScreen error={error} />}
    autoNotifyReady={false}
  >
    <App />
  </TrackerPluginProvider>,
);
```

#### Example (disabling automatic notification) {#tracker-plugin-provider-example-disable-notify}

```tsx
import { TrackerPluginProvider, hostApi } from '@weavix/sdk-react';

function App() {
  useEffect(() => {
    // Perform additional initialization, then notify the host
    initializeApp().then(() => {
      hostApi.notifyReady()
    });
  }, []);

  return <div>My Plugin</div>;
}

root.render(
  <TrackerPluginProvider autoNotifyReady={false}>
    <App />
  </TrackerPluginProvider>,
);
```

## Hooks {#hooks}

### useTrackerPluginContext {#use-tracker-plugin-context}

A hook for getting the theme, language, and slot context from [`TrackerPluginProvider`](#trackerpluginprovider). Supports several overloads depending on `level` and the generic parameter `TSlot`.

#### Type Signature {#use-tracker-plugin-context-type-signature}

```typescript
// level: 'basic' — basic context (entityId and entityMeta only), the slotContext type is narrowed by checking slot
function useTrackerPluginContext(level: 'basic'): {
    [K in keyof SlotContextMap]: BasicTrackerPluginContextValue<K>;
}[keyof SlotContextMap];

// level: 'full' — full context with live entity data
function useTrackerPluginContext(level: 'full'): {
    [K in keyof SlotContextMap]: FullTrackerPluginContextValue<K>;
}[keyof SlotContextMap];

// With generic TSlot and level: 'basic' — typed basic context for a specific slot
function useTrackerPluginContext<TSlot extends keyof SlotContextMap>(
    level: 'basic',
): BasicTrackerPluginContextValue<TSlot>;

// With generic TSlot and level: 'full' — typed full context for a specific slot
function useTrackerPluginContext<TSlot extends keyof SlotContextMap>(
    level: 'full',
): FullTrackerPluginContextValue<TSlot>;
```

#### Parameters {#use-tracker-plugin-context-parameters}

- `level` — `'basic' | 'full'` (required) — the slot context level. Must match the `contextLevel` value specified for the slot in `manifest.json`. For more details, see [Slot context levels](https://yandex.ru/support/tracker/en/plugins/common.md#context-levels).

#### Type Parameters {#use-tracker-plugin-context-type-parameters}

- `TSlot` — the slot type (optional). With the generic — `slotContext` is typed for this slot. Without the generic — you can narrow it with `slot === 'issue.action'`, and so on.

#### Returns {#use-tracker-plugin-context-returns}

[`BasicTrackerPluginContextValue<TSlot>`](#trackerplugincontextvalue) or [`FullTrackerPluginContextValue<TSlot>`](#trackerplugincontextvalue) depending on `level`, or a union across all slots.

#### Throws {#use-tracker-plugin-context-throws}

- `Error` - if used outside [`TrackerPluginProvider`](#trackerpluginprovider)

#### Example (basic context) {#use-tracker-plugin-context-example-basic}

```tsx
import { useTrackerPluginContext } from '@weavix/sdk-react';

function MyComponent() {
  const { theme, language, slotContext } = useTrackerPluginContext('basic');
  // slotContext.entityId — identifier of the current entity
  // slotContext.entityMeta — additional basic metadata (optional)

  return (
    <div className={theme}>
      <p>Language: {language}</p>
      <p>Entity ID: {slotContext.entityId}</p>
    </div>
  );
}
```

#### Example (basic — slot is known) {#use-tracker-plugin-context-example-basic-known-slot}

```tsx
const { slotContext } = useTrackerPluginContext<'issue.action'>('basic');
slotContext.entityId; // issue identifier
slotContext.entityMeta; // additional metadata
```

#### Example (multiple slots — narrowing by slot) {#use-tracker-plugin-context-example-narrowing}

```tsx
const { slot, slotContext } = useTrackerPluginContext('basic');
if (slot === 'issue.action') {
  slotContext.entityId; // here slotContext is typed for the issue.action slot
}
```

#### Example (full context with slot typing) {#use-tracker-plugin-context-example-full}

```tsx
import { useTrackerPluginContext } from '@weavix/sdk-react';

function IssuePlugin() {
  // In manifest.json for the slot: contextLevel: "full"
  const { theme, language, slotContext } = useTrackerPluginContext<'issue.action'>('full');
  return (
    <div>
      <h1>Issue: {slotContext.key}</h1>
      <p>Version: {slotContext.version}</p>
      <p>Theme: {theme}</p>
    </div>
  );
}
```

### useLocalizedString {#use-localized-string}

A hook for getting a localized string based on the current language from the [`TrackerPluginProvider`](#trackerpluginprovider) context.

#### Type Signature {#use-localized-string-type-signature}

```typescript
function useLocalizedString(fallbackLanguage?: string): (value: LocalizedString) => string;
```

#### Parameters {#use-localized-string-parameters}

- `fallbackLanguage` - `string` (optional, defaults to 'en') - the fallback language if the main one isn't found

#### Returns {#use-localized-string-returns}

A function for localizing strings, `(value: LocalizedString) => string`.

#### Example (basic usage) {#use-localized-string-example-basic}

```tsx
import { useLocalizedString } from '@weavix/sdk-react';

function MyComponent() {
  const localize = useLocalizedString();

  const field = {
    name: { ru: 'Имя', en: 'Name' },
    description: { ru: 'Описание', en: 'Description' },
  };

  return (
    <div>
      <h1>{localize(field.name)}</h1>
      <p>{localize(field.description)}</p>
    </div>
  );
}
```

#### Example (with a fallback language) {#use-localized-string-example-fallback}

```tsx
import { useLocalizedString } from '@weavix/sdk-react';

function MyComponent() {
  // If no translation is found for the current language, Russian is used
  const localize = useLocalizedString('ru');

  const name = { en: 'Name' }; // no Russian translation

  return <div>{localize(name)}</div>; // returns 'Name'
}
```

#### Example (working with issue fields) {#use-localized-string-example-fields}

```tsx
import {
  useLocalizedString,
  useTrackerPluginContext,
} from '@weavix/sdk-react';
import { trackerApi } from '@weavix/sdk-react';

function FieldsList() {
  const localize = useLocalizedString();
  const { slotContext } = useTrackerPluginContext<'issue.action'>();
  const [fields, setFields] = useState([]);

  useEffect(() => {
    trackerApi.v3.get['/fields/...']({ ... }).then(setFields);
  }, []);

  return (
    <ul>
      {fields.map((field) => (
        <li key={field.id}>
          <strong>{localize(field.name)}</strong>
          {field.description && <p>{localize(field.description)}</p>}
        </li>
      ))}
    </ul>
  );
}
```

### useToaster {#use-toaster}

A hook for showing toast notifications in the host application. Returns an object with an `add` method.

{% note info "Permission" %}

The `tracker:ui:toaster` permission must be requested in `manifest.json`:

```json
{
    "permissions": {
        "ui": ["toaster"]
    }
}
```

{% endnote %}

```tsx
import { useToaster } from '@weavix/sdk-react';

function MyComponent() {
  const toaster = useToaster();

  const handleSave = async () => {
    await saveData();
    toaster.add({
      title: 'Saved',
      theme: 'success',
    });
  };

  const handleDelete = async () => {
    await deleteItem(id);
    toaster.add({
      title: 'Deleted',
      theme: 'info',
      content: 'QUEUE-123',
      actions: [
        {
          label: 'Undo',
          onClick: () => restoreItem(id),
        },
      ],
    });
  };

  return (
    <div>
      <button onClick={handleSave}>Save</button>
      <button onClick={handleDelete}>Delete</button>
    </div>
  );
}
```

The full list of `add(options)` parameters is in [core](https://yandex.ru/support/tracker/en/plugins/tools/sdk/core.md#toasts).

### useConfirm {#use-confirm}

A plugin can show a modal confirmation dialog. The dialog is rendered **on the Tracker side**, not inside the iframe, so it overlays the entire application and focuses the user on making a decision.

{% note info "Permission" %}

The `tracker:ui:confirm` permission must be requested in `manifest.json`:

```json
{
    "permissions": {
        "ui": ["confirm"]
    }
}
```

{% endnote %}

```tsx
import { useConfirm } from '@weavix/sdk-react';

function DeleteButton() {
    const confirm = useConfirm();

    const handleClick = async () => {
        const { confirmed } = await confirm.show({
            title: 'Delete',
            message: 'Are you sure you want to delete this? This action cannot be undone.',
            textButtonApply: 'Delete',
            textButtonCancel: 'Cancel',
            theme: 'danger',
        });

        if (confirmed) {
            // perform the action
        }
    };

    return <button onClick={handleClick}>Delete</button>;
}
```

The full list of parameters is in [core](https://yandex.ru/support/tracker/en/plugins/tools/sdk/core.md#confirm).

## Types {#types}

### TrackerPluginProviderProps {#tracker-plugin-provider-props}

Props of the [`TrackerPluginProvider`](#trackerpluginprovider) component.

```typescript
interface TrackerPluginProviderProps {
  /** Child elements */
  children: ReactNode;

  /**
   * Automatically resize the plugin container when its content changes
   * @default true
   */
  autoResize?: boolean;

  /**
   * Component to display during initialization
   * @default <PluginLoader />
   */
  fallback?: ReactNode;

  /**
   * Component to display on an initialization error
   * @default <PluginError error={error} />
   */
  errorFallback?: (error: Error) => ReactNode;

  /**
   * Automatically notify the host that the plugin is ready after initialization
   * @default true
   */
  autoNotifyReady?: boolean;
}
```

#### Properties {#tracker-plugin-provider-props-properties}

#|
|| **Property** | **Type** | **Required** | **Default** | **Description** ||
|| `children` | `ReactNode` | Yes | — | Child components rendered after successful initialization ||
|| `autoResize` | `boolean` | No | `true` | Automatically resize the plugin container when its content changes. Enables DOM change tracking and automatically sends the new height to the host ||
|| `fallback` | `ReactNode` | No | The built-in `<PluginLoader />` component | Component shown while the plugin is initializing ||
|| `errorFallback`
|

```ts
(error: Error) =>
  ReactNode
```

| No | The built-in component
```
<PluginError
error={error} />
```
| A function that returns a component to show on an initialization error ||
|| `autoNotifyReady` | `boolean` | No | `true` | Automatically notify the host that the plugin is ready after initialization ||
|#

Usage examples for the properties are in the [Components](#trackerpluginprovider) section above.

{% note info "Elements with relative height" %}

If you use elements with relative height (vh, %, and so on), automatic resizing (`autoResize`) may behave unexpectedly.
If you still want to use components with relative height, disable automatic resizing.

{% endnote %}

### TrackerPluginContextValue {#tracker-plugin-context-value}

The context value provided by [`TrackerPluginProvider`](#trackerpluginprovider). The `slotContext` type depends on the requested context level (`level`).

#### BasicTrackerPluginContextValue {#basic-tracker-plugin-context-value}

Returned when `level: 'basic'`. `slotContext` contains only the entity identifier and basic metadata.

```typescript
interface BasicTrackerPluginContextValue<TSlot extends keyof SlotContextMap = keyof SlotContextMap> {
  theme: Theme;
  language: string;
  /** Name of the slot the plugin is opened in */
  slot: TSlot;
  /** Basic slot context */
  slotContext: {
    /** Identifier of the current entity */
    entityId: string;
    /** Additional basic information.
     *  For example, for a comment, it contains the parent issue's identifier. */
    entityMeta?: Record<string, string>;
  };
}
```

#### FullTrackerPluginContextValue {#full-tracker-plugin-context-value}

Returned when `level: 'full'`. `slotContext` contains the full entity data (the format matches the public API types).

```typescript
interface FullTrackerPluginContextValue<TSlot extends keyof SlotContextMap = keyof SlotContextMap> {
  theme: Theme;
  language: string;
  /** Name of the slot the plugin is opened in */
  slot: TSlot;
  /** Full slot context (depends on the slot type) */
  slotContext: SlotContextMap[TSlot];
}
```

#### Properties (common to both types) {#tracker-plugin-context-value-properties}

#|
|| Property      | Type  | Description  |
|| `theme`       |
```
Theme ('light' | 'light-hc'
  | 'dark' | 'dark-hc' | 'system')
```
| The host's current color theme  ||
|| `language`    | `string` | Code of the host's current language (for example, `'ru'`, `'en'`)  ||
|| `slot`        | `TSlot` (a key from `SlotContextMap`) | Name of the slot the plugin is opened in (for example, `'issue.action'`, `'navigation'`) ||
|| `slotContext` |
```
{ entityId: string;
  entityMeta?: Record<string, string> }
```
at `level: 'basic'`,
`SlotContextMap[TSlot]` at `level: 'full'` |
The context of the slot the plugin runs in. At `basic` — only the entity identifier and metadata. At `full` — the full entity object (for `'issue.action'` — the `Issue` type from the `@weavix/tracker-api-types` package, for `'navigation'` — an empty object `{}`) ||
|#

#### Example (basic) {#tracker-plugin-context-value-example-basic}

```tsx
const { theme, language, slotContext } = useTrackerPluginContext<'issue.action'>('basic');
const isDark = theme === 'dark' || theme === 'dark-hc';
console.log(slotContext.entityId); // 'abc123'
console.log(slotContext.entityMeta); // { issueId: 'QUEUE-123' } — for a comment
```

#### Example (full) {#tracker-plugin-context-value-example-full}

```tsx
// In manifest.json for the slot: contextLevel: "full"
const { slotContext } = useTrackerPluginContext<'issue.action'>('full');
console.log(slotContext.key); // 'QUEUE-123'
console.log(slotContext.version); // 42
```

## Public API {#public-api}

The `@weavix/sdk-react` package re-exports **hostApi**, **trackerApi**, **storageApi**, and types from `@weavix/sdk-core`.

- **hostApi** — interacting with the host: initialization, theme, language, slot context, window size, `notifyReady()`. For more details, see [API Reference core](https://yandex.ru/support/tracker/en/plugins/tools/sdk/core.md#notifyReady).
- **trackerApi** — calls to the Tracker Public API through the **typed v3 API**: `trackerApi.v3.get`, `trackerApi.v3.post`, `trackerApi.v3.put`, `trackerApi.v3.patch`, `trackerApi.v3.delete`. The keys are endpoint paths with autocomplete and JSDoc from `@weavix/tracker-api-types`. Description of methods and formats: [Common format](https://yandex.ru/support/tracker/en/api-ref/common-format.md).
- **storageApi** — the plugin's organization-level JSON storage. For more details, see [Data storage](https://yandex.ru/support/tracker/en/plugins/storage.md).

#### Example {#public-api-example}

```ts
import { trackerApi } from '@weavix/sdk-react';

const issue = await trackerApi.v3.get['/issues/{id}']({
  pathParams: { id: 'KEY-1' },
  queryParams: { expand: ['COMMENTS'] },
});
```

The theme, language, and slot context are available through `useTrackerPluginContext`. Initialization and notifying the host are done through **hostApi**, or inside `TrackerPluginProvider`. Tracker endpoint calls are made through **trackerApi.v3**.

**Full API documentation (types, error codes, utilities):**

[API Reference — @weavix/sdk-core](https://yandex.ru/support/tracker/en/plugins/tools/sdk/core.md)

## Utilities {#utils}

### getLocalizedString {#get-localized-string}

Gets a localized string based on the language. Useful for localization outside React components, or when you need direct control over the language.

#### Type Signature {#get-localized-string-type-signature}

```typescript
function getLocalizedString(
  value: LocalizedString,
  language: string,
  fallbackLanguage?: string,
): string;
```

#### Parameters {#get-localized-string-parameters}

- `value` - `LocalizedString` - the localized string (can be a string or an object with translations)
- `language` - `string` - the language code ('ru' or 'en')
- `fallbackLanguage` - `string` (optional, defaults to 'en') - the fallback language if the main one isn't found

#### Returns {#get-localized-string-returns}

`string` - the localized string in the specified language.

#### Example (basic usage) {#get-localized-string-example-basic}

```tsx
import { getLocalizedString } from '@weavix/sdk-react';
import type { LocalizedString } from '@weavix/sdk-react';

function getFieldName(name: LocalizedString, language: string): string {
  return getLocalizedString(name, language);
}
// language can be obtained from useTrackerPluginContext() in the component

const name = { ru: 'Название', en: 'Summary' };
const localizedName = getFieldName(name, 'ru');
console.log(localizedName); // 'Название'
```

#### Example (with a fallback language) {#get-localized-string-example-fallback}

```tsx
import { getLocalizedString } from '@weavix/sdk-react';

// If the Russian translation is missing, English is used
const partial = { en: 'Name' };
const name = getLocalizedString(partial, 'ru', 'en');
console.log(name); // 'Name'

// If a plain string is passed, it's returned as is
const simple = 'Simple string';
const result = getLocalizedString(simple, 'ru');
console.log(result); // 'Simple string'
```

#### Example (in an event handler) {#get-localized-string-example-handler}

```tsx
import {
  getLocalizedString,
  useTrackerPluginContext,
} from '@weavix/sdk-react';
import type { LocalizedString } from '@weavix/sdk-react';

type FieldWithName = { id: string; name: LocalizedString };

function FieldSelector({ fields }: { fields: FieldWithName[] }) {
  const { language } = useTrackerPluginContext();
  const handleFieldSelect = (field: FieldWithName) => {
    const localizedName = getLocalizedString(field.name, language);
    alert(`Selected field: ${localizedName}`);
  };

  return (
    <ul>
      {fields.map((field) => (
        <li key={field.id} onClick={() => handleFieldSelect(field)}>
          {field.id}
        </li>
      ))}
    </ul>
  );
}
```

{% note info "Note" %}

In React components, it's preferable to use the [`useLocalizedString`](#uselocalizedstring) hook, which automatically gets the language from the context:

```tsx
import { useLocalizedString } from '@weavix/sdk-react';

function MyComponent() {
  const localize = useLocalizedString();

  const field = { name: { ru: 'Название', en: 'Title' } };
  return <div>{localize(field.name)}</div>;
}
```

{% endnote %}