Guided Recommendations Configuration

Custom Text

Option: customText Type: Object Default: null

Description: Allows customization of text within the Guided Recommendations modal and results displays.

Supported Slugs:

Example:

$(%DIV_ELEMENT%).preferabliGR({
    ...configuration_settings,
    customText: {
        'questionnaire.heading': 'Find Your Perfect Match',
        'questionnaire.getrecsbtn': 'Show My Recommendations',
        'result.resultsheading': 'Your Recommendations',
        'result.modifybtn': 'Modify Selections',
    },
});

Localization

Language Support

Option: lang
Type: String
Default: 'en'

Description:
Sets the display language for all text in the Guided Recommendations widget, including headings, labels, and UI elements. This enables you to provide a localized experience for international customers. The widget will automatically translate default headings, "Powered by" text, and other interface elements into the selected language.

Note that this only affects the widget's UI text. Your custom product card content and descriptions would need to be localized separately through your e-commerce platform or renderProductCards function.

Supported Languages:

Example:

// Spanish language site
$(%DIV_ELEMENT%).preferabliGR({
    lang: 'es'
});

Allowed Languages

Option: allowedLanguage
Type: Array of String
Default: null (all languages allowed)

Description:
Restricts which languages can be displayed in the widget. When set, the widget will only use languages from this list, even if the user's browser or lang setting requests a different language. If the requested language is not in the allowed list, the widget will fall back to the defaultLanguage.

This is useful for sites that only support a specific subset of languages or when you want to ensure consistency across your site's supported languages. For example, if your product catalog is only available in English, Spanish, and French, you can restrict the widget to only those languages.

Example:

// Only allow English, Spanish, and French
$(%DIV_ELEMENT%).preferabliGR({
    allowedLanguage: ['en', 'es', 'fr'],
    defaultLanguage: 'en'  // Fallback if user's language isn't allowed
});

Default Language

Option: defaultLanguage
Type: String
Default: 'en'

Description:
Sets the fallback language to use when the requested language is not available or not in the allowedLanguage list. This ensures the widget always displays in a language you support, even when the user's browser language or lang setting specifies an unsupported language.

The defaultLanguage should always be included in your allowedLanguage array (if you're using that option) and should be a language you've fully tested and localized for.

Example:

// English as fallback for European site
$(%DIV_ELEMENT%).preferabliGR({
    allowedLanguage: ['en', 'es', 'fr', 'de', 'it'],
    defaultLanguage: 'en'
});

Results Page Redirect URL

Option: resultsRedirect Type: String

Description: Defines the URL or relative path for the results page.

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  resultsRedirect: '/results',
});

Results Per Page

Option: resultsPerPage Type: Number Default: 6

Description: Number of results displayed per page (1–6).

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  resultsPerPage: 4,
});

Open Product in New Tab

Option: openNewTab Type: Boolean Default: false

Description: Opens product pages in a new tab.

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  openNewTab: true,
});

Show Question Numbers

Option: showQuestionNumbers Type: Boolean Default: true

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  showQuestionNumbers: false,
});

Show Questionnaire On Load

Option: showQuestionnaireOnLoad
Type: Boolean
Default: true

Description:
Loads the questionnaire modal automatically when there are no existing recommendations to display.

Example:

$(%DIV_ELEMENT%).preferabliGR({
    showQuestionnaireOnLoad: false,
});

Show Choice Checkmark

Option: showChoiceCheckmark
Type: Boolean
Default: true

Description:
Enables a CSS attribute that allows visible checkmarks to be displayed on selected choices.

Example:

$(%DIV_ELEMENT%).preferabliGR({
    showChoiceCheckmark: true,
});

Types Plural

Option: typesPlural Type: Boolean Default: false

Description: Converts types to plural format.

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  typesPlural: true,
});

Developer Mode

Option: devMode Type: Boolean Default: false

Description: Hides results using display: none for development purposes.

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  devMode: true,
});

Sidemenu Sticky Top

Option: sidemenuStickyTop Type: String | Number Default: '50px'

Description: Controls top offset for sticky side menu.

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  sidemenuStickyTop: '100px',
});

Sidemenu Static

Option: sidemenuStatic Type: Boolean Default: false

Description: Disables fixed positioning of side menu.

Note: If parent elements use transform: translate3d, fixed positioning may not work.

Example:

$(%DIV_ELEMENT%).preferabliGR({
  ...configuration_settings,
  sidemenuStatic: true,
});

Modal Footnote

Option: modal.footnote
Type: String
Default: null

Description:
Displays custom HTML or plain text at the bottom of the questionnaire modal.

Example:

$(%DIV_ELEMENT%).preferabliGR({
    modal: {
        footnote: 'Recommendations are personalized based on your selections.',
    },
});

Modal Logo

Option: modal.logo
Type: Object
Default: null

Description:
Displays a custom logo or HTML content inside the questionnaire modal.

Properties:

• position — Logo position inside the modal.
• content — HTML content or image URL to display, script tags will be removed.
• class — HTML appended to the element, comma separated or spaced string allowed
• wrapper_element — HTML tag to wrap the element, default: div

Position Values:

top-left | top-center | top-right | bottom-left | bottom-center | bottom-right

Example:

$(%DIV_ELEMENT%).preferabliGR({
    modal: {
        logo: {
            position: 'top-center',
            content: 'https://example.com/logo.png',
            class: 'brand_logo`
        },
    },
});

Powered by Preferabli - Logo Placement

Option: logo_placement Type: String Default: 'results'

Values: results | sidebar

Description: Sets where the logo appears on the results screen.

Results Layout

Option: layout Type: String Default: 'row'

Values: row | column

Description: Controls layout of results.

Show Decimal Places

Option: showDecimalPlaces Type: Boolean Default: true

Example:

$(%DIV_ELEMENT%).preferabliGR({
    ...configuration_settings,
    showDecimalPlaces: true,
});

Number of Decimal Places

Option: numDecimalPlaces Type: Number Default: 2

Example:

$(%DIV_ELEMENT%).preferabliGR({
    ...configuration_settings,
    numDecimalPlaces: 2,
});

Default Modal Question

Option: modifyQuestionShow Type: Number

Description: Sets which question is shown when reopening questionnaire.

Example:

$(%DIV_ELEMENT%).preferabliGR({
    ...configuration_settings,
    modifyQuestionShow: 4,
});

Opt Out Tracking

Option: opt_out_tracking
Type: Boolean
Default: false

Description:
Allows you to opt a user out of tracking based on cookie consent or privacy preferences.
When enabled, tracking-related data will not be collected for the session.

This is typically triggered after a user declines cookies or opts out via a privacy control.

Example:

$(%DIV_ELEMENT%).preferabliGR({
    ...configuration_settings,
    opt_out_tracking: true, // disable tracking on initialization
});
//
$(BUTTON).on('click', function() {
  $(%DIV_ELEMENT%).preferabliGR('optOutTracking', false); // to enable tracking after accepted cookies
});

**Notes:**
- Can be toggled dynamically after initialization
- Recommended to integrate with your site's cookie consent manager
- Applies to all instances of Preferabli Widgets

Custom Styling

Option: customStyling Type: Object Default: null

Description: Customize CSS classes for Guided Recommendations components.

Structure:

customStyling: {
  questionnaire: {
    heading,
    container,
    selector,
    selectorLabel,
    rangeTrack,
    rangeTrackActive,
    rangeDrag,
  },
  results: {
    heading,
    container,
    productCard,
    productCardBtn,
    rowEl,
    rowClass,
  },
  sidemenu: {
    item,
    itemActive,
    modifySearchBtn,
    backToTopBtn
  },
  basicButton,
  loadingColor
}

Custom Product Cards

Option: renderProductCards Type: Function Default: null

Description: Allows custom rendering of product cards.

Example:

$(%DIV_ELEMENT%).preferabliGR('show', {
    type: 'results',
    element: $('#guidedrec'),
    renderProductCards: (lookups) => {
        return Promise.resolve([
            ...lookups.map(() => '%_YOUR_CARD_TEMPLATE_%')
        ]);
    }
});

Product Cards Container

Option: productCardsContainer
Type: Object
Default: null

Description:
Customize the HTML container element that wraps all product cards. This allows the STP widget to integrate seamlessly with your existing CSS framework or e-commerce platform. For example, WooCommerce typically uses <ul class="products"> to contain product listings, so you can configure the container to match this structure.

Without this option, the STP widget uses its default container structure, which may not inherit your site's existing product grid styles.

Properties:

• element - The HTML tag name for the container (e.g., 'ul', 'div', 'section')
• class - CSS class name(s) to apply to the container
• id - Unique identifier for the container element

Example:

$(%DIV_ELEMENT%).preferabliGR({
    productCardsContainer: {
        element: 'ul',           // Uses <ul> instead of default <div>
        class: 'products',       // Matches WooCommerce class
        id: 'stp-container'      // Custom ID for targeting
    }
});

Important: Ensure these match your existing ecommerce system display

Render Complete Callback

Option: onRenderComplete
Type: Function
Default: null
Required when: renderProductCards is used

Description:
This callback function executes immediately after the STP widget finishes rendering all product cards. It's useful for initializing third-party libraries, triggering analytics events, lazy-loading images, or any other post-render operations.

The function is called with no arguments and should not return a value. Any code inside this function will run after the DOM has been updated with the product recommendations.

Example:

$(%DIV_ELEMENT%).preferabliGR('show', {
    type: 'results',
    element: $('#guidedrec'),
    renderProductCards: () => Promise.resolve([]),
    onRenderComplete: function () {
        // callback
    }
});

Sorting

Option: enable_sort Type: Boolean Default: false

Description: Enables sorting by recommendation and price.

Example:

$(%DIV_ELEMENT%).preferabliGR({
    ...configuration_settings,
    enable_sort: true,
});

Placeholder

Option: placeholder Type: Object Default: null

Description: Customizes placeholder content for default, no results, or error states.

Structure:

placeholder: {
  defaults: {
    text,
    instantRecButton
  },
  noresults: {
    text,
    instantRecButton
  },
  error: {
    text,
    redirectButton,
    timeout
  }
}

Example:

placeholder: {
  defaults: {
    text: 'Try our quiz to get your recommendations.',
    instantRecButton: {
      text: 'Find Your Recommendation'
    }
  }
}

Default Placeholder Copy

Default

• Main Heading: Get Personalized Recommendations, Instantly.
• Sub Heading: Find what you're looking for within seconds.

No Results

• Main Heading: We were unable to find any recommendations.
• Sub Heading: Let's try different selections.

Error

• Main Heading: We are unable to process your recommendation.
• Sub Heading: Please try adjusting your selections.