@itwin/itwinui-react/esm/core/ThemeProvider/ThemeProvider.d.ts

A react component library for iTwinUI

import * as React from 'react';
import type { FutureOptions, PolymorphicForwardRefComponent } from '../../utils/index.js';
export type ThemeOptions = {
    /**
     * Whether to apply high-contrast versions of light and dark themes.
     * Will default to user preference if browser supports it.
     */
    highContrast?: boolean;
};
export type ThemeType = 'light' | 'dark' | 'os';
type RootProps = {
    /**
     * Theme to be applied. Can be 'light' or 'dark' or 'os'.
     *
     * Note that 'os' will respect the system preference on client but will fallback to 'light'
     * in SSR environments because it is not possible detect system preference on the server.
     * This can cause a flash of incorrect theme on first render.
     *
     * The 'inherit' option is intended to be used by packages, to enable incremental adoption
     * of iTwinUI while respecting the theme set by the consuming app. It will fall back to 'light'
     * if no parent theme is found. Additionally, it will attempt to inherit `themeOptions.highContrast`
     * and `portalContainer` (if possible).
     *
     * `future.themeBridge` will be inherited regardless of `theme` value. To disable it, explicitly set
     * `future.themeBridge` to false.
     *
     * @default 'inherit'
     */
    theme?: ThemeType | 'inherit';
    themeOptions?: Pick<ThemeOptions, 'highContrast'> & {
        /**
         * Whether or not the element should apply the recommended `background-color` on itself.
         *
         * When not specified, the default behavior is to apply a background-color only
         * if it is the topmost `ThemeProvider` in the tree. Nested `ThemeProvider`s will
         * be detected using React Context and will not apply a background-color.
         *
         * Additionally, if theme is set to `'inherit'`, then this will default to false.
         *
         * When set to true or false, it will override the default behavior.
         */
        applyBackground?: boolean;
    };
};
type ThemeProviderOwnProps = Pick<RootProps, 'theme'> & {
    themeOptions?: RootProps['themeOptions'];
    children: Required<React.ReactNode>;
    /**
     * The element used as the portal for floating elements (Tooltip, Toast, DropdownMenu, Dialog, etc).
     *
     * Defaults to a `<div>` rendered at the end of the ThemeProvider.
     *
     * When passing an element, it is recommended to use state.
     *
     * @example
     * const [myPortal, setMyPortal] = React.useState(null);
     *
     * <div ref={setMyPortal} />
     * <ThemeProvider
     *   portalContainer={myPortal}
     * >
     *   ...
     * </ThemeProvider>
     */
    portalContainer?: HTMLElement;
    /**
     * This prop will be used to determine if `styles.css` should be automatically imported at runtime (if not already found).
     *
     * By default, this is enabled when using `theme='inherit'`.
     * This default behavior is useful for packages that want to support incremental adoption of latest iTwinUI,
     * without requiring consuming applications (that might still be using an older version) to manually import the CSS.
     *
     * If true or false is passed, it will override the default behavior.
     */
    includeCss?: boolean;
    /**
     * Options to help with early adoption of features from future versions.
     *
     * All future options will be automatically inherited across nested ThemeProviders, unless explicitly overridden.
     */
    future?: true | FutureOptions;
};
/**
 * This component provides global state and applies theme to the entire tree
 * that it is wrapping around.
 *
 * The `theme` prop defaults to "inherit", which looks upwards for closest ThemeProvider
 * and falls back to "light" theme if one is not found.
 *
 * If you want to theme the entire app, you should use this component at the root. You can also
 * use this component to apply a different theme to only a part of the tree.
 *
 * By default, the topmost `ThemeProvider` in the tree will apply the recommended
 * `background-color`. You can override this behavior using `themeOptions.applyBackground`.
 *
 * @example
 * <ThemeProvider theme='os'>
 *  <App />
 * </ThemeProvider>
 *
 * @example
 * <ThemeProvider as='body'>
 *   <App />
 * </ThemeProvider>
 *
 * @example
 * <ThemeProvider theme='dark' themeOptions={{ applyBackground: false }}>
 *  <App />
 * </ThemeProvider>
 */
export declare const ThemeProvider: PolymorphicForwardRefComponent<"div", ThemeProviderOwnProps>;
export {};