Function useSetting

Gets, sets and resets a setting on the PAPI. Also notifies subscribers when the setting changes and gets updated when the setting is changed by others.

Throws

When subscription callback function is called with an update that has an unexpected message type

  • useSetting<SettingName extends keyof SettingTypes>(
        key: SettingName,
        defaultState: SettingTypes[SettingName],
        subscriberOptions?: DataProviderSubscriberOptions,
    ): [
        setting: PlatformError
        | SettingTypes[SettingName],
        setSetting: (
            newData: SettingTypes[SettingName],
        ) => Promise<DataProviderUpdateInstructions<SettingDataTypes>>,
        resetSetting: () => void,
        isLoading: boolean,
    ]

    Type Parameters

    Parameters

    • key: SettingName

      The string id that is used to identify the setting that will be stored on the PAPI

      WARNING: MUST BE STABLE - const or wrapped in useState, useMemo, etc. The reference must not be updated every render

    • defaultState: SettingTypes[SettingName]

      The initial value to return while first awaiting the setting value

    • OptionalsubscriberOptions: DataProviderSubscriberOptions

      Various options to adjust how the subscriber emits updates

      Note: this parameter is internally assigned to a ref, so changing it will not cause any hooks to re-run with its new value. This means that subscriberOptions will be passed to the data provider's subscribe<data_type> method as soon as possible and will not be updated again until dataProviderSource or selector changes.

    Returns [
        setting: PlatformError
        | SettingTypes[SettingName],
        setSetting: (
            newData: SettingTypes[SettingName],
        ) => Promise<DataProviderUpdateInstructions<SettingDataTypes>>,
        resetSetting: () => void,
        isLoading: boolean,
    ]

    [setting, setSetting, resetSetting]

    • setting: The current state of the setting, either defaultState, the stored value, or a PlatformError if loading the value fails. Use isPlatformError() to check.
    • setSetting: Function that updates the setting to a new value
    • resetSetting: Function that removes the setting and resets the value to defaultState

Settings

Member Visibility