Options
All
  • Public
  • Public/Protected
  • All
Menu

Module "index"

Index

Type aliases

Variables

Functions

Type aliases

AmbientContextType

AmbientContextType: { activeData: any | null; activeKey: string | null; backgroundElement: HTMLDivElement | null; dataByKey: Record<string, any>; groupId: string }

Type declaration

  • activeData: any | null

    The user data for the currently active content

  • activeKey: string | null

    The currently active content key

  • backgroundElement: HTMLDivElement | null

    An element ref to the background element

  • dataByKey: Record<string, any>

    All user data, keyed by content id

  • groupId: string

    The context provider's group id, used internally by useAmbient

AmbientProviderProps

AmbientProviderProps: HTMLAttributes<HTMLDivElement> & { backgroundElementProps?: React.HTMLAttributes<HTMLDivElement>; debounceTimeout?: undefined | number; groupId?: undefined | string }

FadingBackgroundProps

FadingBackgroundProps: HTMLAttributes<HTMLDivElement> & { active: boolean; fadeDurationSeconds?: undefined | number }

UseAmbientBindProps

UseAmbientBindProps: { __computed: string }

Props which you should pass to your content component

Type declaration

  • __computed: string

UseAmbientOptions

UseAmbientOptions<D, T>: { WrapperComponent?: React.ComponentType<T> | null; data?: D; getWrapperProps?: undefined | ((state: { active: boolean; activeData: D | null; activeKey: string | null }) => T); key?: undefined | string }

Type parameters

  • D

  • T

Type declaration

  • Optional WrapperComponent?: React.ComponentType<T> | null

    By default, backgrounds will fade to transition from one to another. You can override this behavior by providing your own wrapper component to implement the transition. If you like, you can provide null to have no transition at all. If you provide a custom WrapperComponent, you probably also want to override the getWrapperProps value to pass the correct props to your component.

    example
    import { Scale } from '@material-ui/core';

function Section() {
  const [props, { renderBackground }] = useAmbient({
    WrapperComponent: Scale,
    getWrapperProps: ({ active }) => ({ in: active })
  });

  return (
    <section {...props}>
      {renderBackground(<BackgroundImage />)}
      Some content
    </section>
  );
}
  • Optional data?: D

    You can provide any arbitrary data you like for this content, which will be made available to all other uses of this hook inside the same parent context. Use this feature for things like choosing a foreground color which is applied to every section based on the current active section, by having each content section pass a color value in data, and then use the color value from the activeData return value to set the CSS foreground color.

    example
    function Section({ color }) {
  const [props, { activeData, renderBackground }] = useAmbient({
    data: { color },
  });

  return (
    // by pulling the color value from activeData, we are using the color
    // as specified by the currently active section, which presumably will
    // have the best contrast with the currently active background.
    <section {...props} style={{ color: activeData && activeData.color }}>
      {renderBackground(<BackgroundImage />)}
      Some content
    </section>
  );
}
  • Optional getWrapperProps?: undefined | ((state: { active: boolean; activeData: D | null; activeKey: string | null }) => T)

    If you provide your own WrapperComponent, it might have specific props it needs to render correctly - use this function to compute the props that will be passed to that component based on the current ambient state. Or, even if you use the default wrapper, you can provide extra props to that wrapper using this function - for example, you can provide fadeDurationSeconds to override the default fade duration on the built-in wrapper. If you override props for the built-in wrapper (i.e. you provide this function without providing WrapperComponent), you must at minimum return an object with active set to state.active.

    example
    function Section() {
  const [props, { renderBackground }] = useAmbient({
    getWrapperProps: ({ active }) => ({ active, fadeDurationSeconds: 1 })
  });

  return (
    <section {...props}>
      {renderBackground(<BackgroundImage />)}
      Some content
    </section>
  );
}
  • Optional key?: undefined | string

    Optionally, you can provide your own key for this content. By providing your own key, you can include logic which utilizes the activeKey value meaningfully.

UseAmbientReturn

UseAmbientReturn<D>: [UseAmbientBindProps, UseAmbientTools<D>]

Type parameters

  • D

UseAmbientTools

UseAmbientTools<D>: { active: boolean; activeData: D | null; activeKey: string | null; renderBackground: (content?: React.ReactNode) => ReactPortal | null }

A set of utilities for interacting with the ambient system. Includes a function you should wrap your background content in when rendering, and information about the currently active content. active will be true if the component which is bound to this hook usage is active.

Type parameters

  • D

Type declaration

  • active: boolean

    Whether the content section which is bound to this hook usage is currently active.

  • activeData: D | null

    The user-defined context data for the active content. This is the value that was passed to the data config property by the currently active content when it called useAmbient.

  • activeKey: string | null

    The key of the currently active content. You can pass your own key to useActive if you want to utilize this meaningfully. Otherwise, it's a random value generated at runtime for each content item.

  • renderBackground: (content?: React.ReactNode) => ReactPortal | null

    Wrap your background React content in this function and call it within your component JSX. You can also omit any content to render a blank background for this content.

      • (content?: React.ReactNode): ReactPortal | null

      • Parameters

        • Optional content: React.ReactNode

        Returns ReactPortal | null

Variables

Const AmbientContext

AmbientContext: Context<{ activeData: any | null; activeKey: string | null; backgroundElement: HTMLDivElement | null; dataByKey: Record<string, any>; groupId: string }> = React.createContext<AmbientContextType>({activeKey: null,backgroundElement: null,activeData: {},dataByKey: {},groupId: 'default',})

Const DATA_ATTRIBUTE_GROUP

DATA_ATTRIBUTE_GROUP: "data-ambient-group" = "data-ambient-group"

The data- attribute used to identify the group a content element belongs to

Const DATA_ATTRIBUTE_KEY

DATA_ATTRIBUTE_KEY: "data-ambient-key" = "data-ambient-key"

The data- attribute used to identify content elements

Functions

AmbientProvider

  • A top-level Provider for the ambient system. Place this component in the React tree above all usages of useAmbient. You can have multiple different ambient systems at once, whether parallel or nested - but note that since the default styling of the background pane is position: fixed, by default multiple usages will collide! To fix this, change the styling of the background pane using backgroundElementProps.

    example
    function AppLayout() {
  return (
    <AmbientProvider
      backgroundElementProps={{ style: { backgroundColor: 'black' } }}
      debounceTimeout={50}
      style={{ zIndex: 500 }}
    >
      <AppContent />
    </AmbientProvider>
  );
}

    Parameters

    Returns Element

FadingBackground

useAmbient

  • Hooks into the ambient background system and provides props to give to your content component, plus utilities for drawing your background and reacting to changes in the active content.

    Type parameters

    • D

    • T

    Parameters

    Returns UseAmbientReturn<D>

Generated using TypeDoc