opensearch-dashboards-react

Tools for building React applications in OpenSearch Dashboards.

Context

You can create React context that holds Core or plugin services that your plugin depends on.

import { createOpenSearchDashboardsReactContext } from 'opensearch-dashboards-react';

class MyPlugin {
  start(core, plugins) {
    const context = createOpenSearchDashboardsReactContext({ ...core, ...plugins });
  }
}

You may also want to be explicit about services you depend on.

import { createOpenSearchDashboardsReactContext } from 'opensearch-dashboards-react';

class MyPlugin {
  start({ notifications, overlays }, { embeddable }) {
    const context = createOpenSearchDashboardsReactContext({ notifications, overlays, embeddable });
  }
}

Wrap your React application in the created context.

<context.Provider>
  <OpenSearchDashboardsApplication />
</context.Provider>

Or use already pre-created <OpenSearchDashboardsContextProvider> component.

import { OpenSearchDashboardsContextProvider } from 'opensearch-dashboards-react';

<OpenSearchDashboardsContextProvider services={{ ...core, ...plugins }}>
  <OpenSearchDashboardsApplication />
</OpenSearchDashboardsContextProvider>

<OpenSearchDashboardsContextProvider services={{ notifications, overlays, embeddable }}>
  <OpenSearchDashboardsApplication />
</OpenSearchDashboardsContextProvider>

Accessing context

Using useOpenSearchDashboards hook.

import { useOpenSearchDashboards } from 'opensearch-dashboards-react';

const Demo = () => {
  const opensearchDashboards = useOpenSearchDashboards();
  return <div>{opensearchDashboards.services.uiSettings.get('theme:darkMode') ? 'dark' : 'light'}</div>;
};

Using withOpenSearchDashboards() higher order component.

import { withOpenSearchDashboards } from 'opensearch-dashboards-react';

const Demo = ({ opensearchDashboards }) => {
  return <div>{opensearchDashboards.services.uiSettings.get('theme:darkMode') ? 'dark' : 'light'}</div>;
};

export default withOpenSearchDashboards(Demo);

Using <UseOpenSearchDashboards> render prop.

import { UseOpenSearchDashboards } from 'opensearch-dashboards-react';

const Demo = () => {
  return (
    <UseOpenSearchDashboards>
      {(opensearchDashboards) => <div>{opensearchDashboards.services.uiSettings.get('theme:darkMode') ? 'dark' : 'light'}</div>}
    </UseOpenSearchDashboards>
  );
};

uiSettings service

Wrappers around Core's uiSettings service.

useUiSetting hook

useUiSetting synchronously returns the latest setting from CoreStart['uiSettings'] service.

import { useUiSetting } from 'opensearch-dashboards-react';

const Demo = () => {
  const darkMode = useUiSetting<boolean>('theme:darkMode');
  return <div>{darkMode ? 'dark' : 'light'}</div>;
};

Reference

useUiSetting<T>(key: string, defaultValue: T): T;

useUiSetting$ hook

useUiSetting$ synchronously returns the latest setting from CoreStart['uiSettings'] service and subscribes to changes, re-rendering your component with latest values.

import { useUiSetting$ } from 'opensearch-dashboards-react';

const Demo = () => {
  const [darkMode] = useUiSetting$<boolean>('theme:darkMode');
  return <div>{darkMode ? 'dark' : 'light'}</div>;
};

Reference

useUiSetting$<T>(key: string, defaultValue: T): [T, (newValue: T) => void];

overlays service

Wrapper around Core's overlays service, allows you to display React modals and flyouts directly without having to use react-dom library to mount to DOM nodes.

import { createOpenSearchDashboardsReactContext } from 'opensearch-dashboards-react';

class MyPlugin {
  start(core) {
    const {
      value: { overlays },
    } = createOpenSearchDashboardsReactContext(core);

    overlays.openModal(<div>Hello world!</div>);
  }
}

• overlays.openModal — opens modal window.
• overlays.openFlyout — opens right side panel.

You can access overlays service through React context.

const Demo = () => {
  const { overlays } = useOpenSearchDashboards();
  useEffect(() => {
    overlays.openModal(<div>Oooops! {errorMessage}</div>);
  }, [errorMessage]);
};

notifications service

Wrapper around Core's notifications service, allows you to render React elements directly without having to use react-dom library to mount to DOM nodes.

import { createOpenSearchDashboardsReactContext } from 'opensearch-dashboards-react';

class MyPlugin {
  start(core) {
    const {
      value: { notifications },
    } = createOpenSearchDashboardsReactContext(core);

    notifications.toasts.show({
      title: <div>Hello</div>,
      body: <div>world!</div>,
    });
  }
}

• notifications.toasts.show() — show generic toast message.
• notifications.toasts.success() — show positive toast message.
• notifications.toasts.warning() — show warning toast message.
• notifications.toasts.danger() — show error toast message.

You can access notifications service through React context.

const Demo = () => {
  const { notifications } = useOpenSearchDashboards();
  useEffect(() => {
    notifications.toasts.danger({
      title: 'Oooops!',
      body: errorMessage,
    });
  }, [errorMessage]);
};

RedirectAppLinks

Utility component that will intercept click events on children anchor (<a>) elements to call application.navigateToUrl with the link's href. This will trigger SPA friendly navigation when the link points to a valid OpenSearch Dashboards app.

<RedirectAppLinks application={application}>
  <a href="/base-path/app/another-app/some-path">Go to another-app</a>
</RedirectAppLinks>