OverviewHI Widget Guide
Member Association integration guide

Search the world,
from your site.

One hosted HI search component for cities, regions and countries—with hostel-name matching and a mobile interface designed for the software keyboard.

Install the widget Download MA pack
10minutes for a typical installation
2standard interface languages
1centrally maintained widget

A small integration, maintained by HI

The widget downloads HI’s public location index, searches it in the visitor’s browser and hands a chosen place to Hostel Explorer. Suggestions are cities, regions and countries; typing a hostel name can surface the places containing that hostel.

HI hosts the component and location data centrally. Member Associations do not need an API key, a software package or a locally hosted copy of the JavaScript.

On mobile, focusing the field opens a full-page search interface. Its results area scrolls independently and remains usable while the software keyboard is visible.

The old widget remains supported during migration. An MA can stage and approve the replacement normally, then roll back to its saved legacy embed if its own CMS or security policy causes a problem.

Search

Location hierarchy

City, region and country layers are always eligible when HI has hostels there.

Mobile

Full-page takeover

A focused interface with its own results scrolling above the keyboard.

Maintenance

One hosted version

Updates and current location data arrive without an MA reinstalling the widget.

Section 02 · Install

Copy, identify, test

Replace YOUR_MA_CODE with the MA’s code from the directory below. Keep the fallback link inside the component.

01

Confirm settings

Look up the MA partner code below, then choose the language and tab behaviour.

02

Add the embed

Place the component in normal page flow and include the module script once.

03

Test and publish

Complete the staging checklist, publish, then repeat the mobile smoke test.

Production embed
<hi-hostel-search
  index-url="https://data.hihostels.com/v1/locations.json"
  search-url="https://widgets.hihostels.com/go/hostels"
  locale="en-GB"
  partner="YOUR_MA_CODE"
  target="_blank">
  <a href="https://www.hihostels.com/discover/explore">Search HI hostels</a>
</hi-hostel-search>
<script type="module" src="https://widgets.hihostels.com/hostel-search/v1/hostel-search.js"></script>

If the widget appears more than once on a page, include the script only once. Do not download, proxy or self-host the component.

Section 03 · Configure

Three decisions per MA

Required

partner

The non-personal attribution code supplied by HI from the canonical MA registry. Copy it exactly; do not invent a code from the MA name or website address.

Required

locale

Use en-GB for English or de-DE for German. Standard copy follows this setting.

Required

target

Use _blank to open Explorer in a new tab, recommended for an external MA site, or _self for the same tab.

Optional copy

Use the defaults where possible

placeholder and button-label can override standard interface text by agreement with HI. Overrides are not automatically translated.

Optional presentation

Choose a size, then apply approved tokens

Add size="large" for a more prominent treatment. The host element also accepts --hi-widget-brand, --hi-widget-brand-hover, --hi-widget-accent, --hi-widget-surface, --hi-widget-field, --hi-widget-text, --hi-widget-radius and --hi-widget-max-width. Apply these properties directly to hi-hostel-search, not only to an ancestor: the component moves to the document layer while search is active. Keep colour contrast accessible and test the focused state on the final MA page.

Responsive spacing

Add breathing room on narrow pages

If the widget's coloured container has no horizontal padding, use the supported maximum-width token to retain a 16 px gutter on each side. This keeps the standard 768 px desktop limit and avoids changing the widget's full-page mobile search interface.

MA stylesheet
hi-hostel-search {
  --hi-widget-max-width: min(768px, calc(100% - 32px));
}

Use a more specific selector if the site contains other HI search widgets. Do not target internal Shadow DOM classes.

Section 04 · MA codes

Find your partner code

Search by Member Association name, country or code, then use the exact code shown in the widget’s partner attribute. Codes are non-personal and are used to attribute search journeys on the HI site.

Loading the current MA code directory…

Section 05 · Test

Try the production widget

This is the same hosted component and continuously refreshed location index an MA will embed. Try Paris, Sydney or the unaccented spelling Cordoba.

Search HI hostels
Desktop

Suggestions and hand-off

  • Search Paris and confirm city and country suggestions.
  • Search Sydney and confirm Sydney, Australia is available as a city.
  • Search Cordoba and confirm accented Córdoba results appear.
Mobile

Keyboard and scrolling

  • Test near 390px on a real phone.
  • Open the software keyboard.
  • Confirm the panel fills the usable screen and results scroll.
Attribution

Destination contract

  • Confirm source=ma-widget.
  • Confirm the agreed partner code.
  • Confirm the chosen place and language.
Section 06 · Migrate

No emergency deadline

The unchanged legacy widget is currently supported by HI’s compatibility service. MAs can schedule and test the replacement normally.

HI intends to maintain the legacy compatibility endpoints for at least 12 months after cutover and until measured use is negligible. HI will communicate before withdrawing support.

  1. 01

    Save the current page

    Keep a CMS revision or exact copy of the old embed.

  2. 02

    Stage the new widget

    Do not show both search interfaces in the same location.

  3. 03

    Complete desktop and mobile QA

    Include a real phone with the keyboard open.

  4. 04

    Publish and smoke-test

    Check the public page in a private browser window.

  5. 05

    Roll back if required

    Restore the saved legacy embed, publish it, then send HI the evidence below.

Section 07 · Technical

Security, privacy and hosting

Content Security Policy

Add both HI service hosts to the relevant existing directives; do not replace the MA’s current sources or nonces.

script-src https://widgets.hihostels.com
style-src https://widgets.hihostels.com
connect-src https://data.hihostels.com

The browser must also be allowed to navigate to widgets.hihostels.com and www.hihostels.com. The widget does not require unsafe-eval or unsafe-inline.

Data and measurement

Suggestions are filtered locally after the public index downloads. The submitted location, language, source=ma-widget and non-personal partner code appear in the destination query string.

The widget does not load HI PostHog or set HI analytics cookies on the MA website. After the visitor reaches the HI site, consented HI analytics can use the partner code to measure the search journey. A booking click is not a confirmed booking.

Do not put names, email addresses, customer IDs or other personal data in widget attributes.

Browser support

The widget targets current evergreen desktop and mobile browsers, including current Safari on iOS and Chrome on Android. Each MA should still test its own supported matrix.

The fallback link remains available if JavaScript cannot run.

Layout boundary

Place the component in normal flow in a container that can use the available width. Do not clip it or give its outer container a fixed height.

Shadow DOM isolates internal styling from the host site.

Section 08 · Support

Send evidence, not personal data

First compare the MA page with the hosted test above. If the hosted test works but the MA embed does not, include the MA page’s console or CSP error.

ZIP

Download the complete MA pack

Embed file, installation guide, QA, rollback, technical notes and support template.

 ↘

Include with a support request

  • MA name, partner code and affected page URL
  • Staging or production environment
  • Date, time, device, operating system and browser
  • Search entered, expected result and actual result
  • Screenshot or short recording
  • Widget-related console or CSP error
  • Recent CMS, consent-manager, CSP or firewall change