Embed Listings on Your Site

Listing embeds show a grid of your listings on a page you control elsewhere: your marketing site, a community page, a blog. The cards link back to your HomeStar search site. One script tag serves every widget on a page. The same snippet, with one attribute changed, puts a search box above the grid so visitors can narrow it themselves (step 5).

The full attribute and endpoint list is in the Listing Embeds reference. This page is the order of operations.

Before you start

Your MLS licenses IDX display to registered sites. Confirm the domain you will embed on is on your MLS participation form before anything goes live. Most MLS rules also prohibit advertising and co-branding on pages that display IDX listings, so a page with a lender or builder logo on it may not be a page that can carry a widget.

---

1. Verify your domain

Embeds are served from a domain that belongs to your brokerage, typically the one your HomeStar search site will live on, such as search.yourbrokerage.com.

1. In the admin dashboard, open Brokerages, choose your brokerage, and go to the Domains tab.
2. Add the hostname if it is not there already.
3. At your DNS provider, create a CNAME for that hostname pointing at the target shown next to the domain.
4. Back in HomeStar, click Verify. The check looks for the CNAME; once it passes, the certificate is issued automatically and the domain starts serving.

Until the domain is verified, nothing is served from it. You can test against your *.homestar.ink tenant hostname in the meantime; the snippet is identical apart from the host.

---

2. Get your key and scopes

Embeds use a public key that identifies your brokerage and named scopes that decide what each widget shows. Both live under Widgets in the admin sidebar.

1. Open Widgets. If there is no key yet, click Create key, give it a label (the site it will live on is a good one), and add the hostname from step 1 under Allowed origins.
2. Under Registered pages, add every page that will carry a widget, so the nightly attribution check knows where to look. You can add to this list any time.
3. Click New scope for each widget you want. The label becomes the widget’s heading; the slug goes in the snippet. Set the filter in plain terms: a city, a status, a price range, a sort. The dialog reads the filter back to you in words before you save.

The key looks like hsx_live_yourbrokerage_7f3a9c2e; the slugs are what you named them, for example hayden, coeur-dalene, showcase. The key is not a secret; it is meant to sit in your page’s HTML. Turning the key off makes every widget using it show its fallback link on the next load, which is the quickest way to pull the grids from a site without touching the pages.

Note

Scopes are named after what they filter, not after the page that mounts them. If a page’s widget should show a different city later, edit the scope, and every page mounting it follows.

For operators: the YAML path

The platform team can also manage keys and scopes from the brokerage’s onboarding file under embeds: in .onboarding/<slug>.yml, applied with make onboard-embeds BROKERAGE=<slug>. The two do not fight: the script matches keys by label and scopes by slug. It does mean a scope edited in the admin whose slug also appears in the YAML is reset to the YAML the next time the file is applied, so when a scope is meant to stay hand-edited, take it out of the file.

---

3. Check the preview

Before touching your site, open the preview for one scope in a browser:

https://search.yourbrokerage.com/embed/v1/preview?key=hsx_live_yourbrokerage_7f3a9c2e&scope=hayden

You should see the heading, the cards, and the MLS attribution block under them. If you see only a “Browse listings” link, either the scope has no matching listings right now or the key and scope do not match. The Snippet tab under Widgets shows the same preview beside the form, at desktop, tablet and phone widths, and updates as you change the options.

To confirm the slugs you were given, the scopes endpoint lists them:

https://search.yourbrokerage.com/embed/v1/scopes?key=hsx_live_yourbrokerage_7f3a9c2e

---

4. Paste the snippet

Put a mount where the grid should appear, and the script tag once, anywhere on the page.

<div class="hs-embed"
     data-hs-embed="listings"
     data-hs-key="hsx_live_yourbrokerage_7f3a9c2e"
     data-hs-scope="hayden"
     data-hs-limit="9"
     data-hs-columns="3"
     data-hs-heading-level="3"
     data-hs-fallback-href="https://search.yourbrokerage.com/search?city=Hayden"
     style="--hs-accent: #4a5d3a">
  <noscript><a href="https://search.yourbrokerage.com/search?city=Hayden">Browse Hayden listings</a></noscript>
</div>
<script src="https://search.yourbrokerage.com/embed/v1/loader.js" async></script>

Things worth setting deliberately:

• data-hs-heading-level so the widget’s title fits your page outline. If the section above it is an <h2>, use 3.
• data-hs-fallback-href to the matching search on your HomeStar site. It is what renders if the widget cannot load.
• --hs-accent and the other custom properties to match the page. If your community pages already have per-page colours, set them here.

The widget does not load until it is close to the viewport, and it reserves its height first, so it will not push your page around while it fetches.

Static sites bake the hostnames in at build time

If your marketing site is prerendered (Astro, Next, Hugo, Eleventy), the data-hs-key, the fallback links and the loader src are written into the HTML when the site is built. Reading them from an environment variable only works if that variable is present during the build, not just on the server that runs the result. A value set in a .env file the build never sees leaves the old hostname in every page, and nothing warns you.

Either write the values into the snippet directly, or pass them as build arguments and then open the built HTML and confirm they are there before you deploy. One brokerage shipped with the previous search hostname in its pages for weeks this way, while its .env said the right thing.

---

5. Put a search box on your site

If your site has a search page today that only hands visitors off, the search widget replaces it: a form, results under it, and the full search one click away. It is the grid widget with data-hs-embed="search".

1. Under Widgets, create a scope for it if there is not one already. Keep it wide: a brokerage-wide scope with a sort is the usual shape, since the visitor’s own filters can only narrow what the scope allows, and a field the scope fixes (a city, a property type) is left off the form.
2. On the Snippet tab, set Widget to Search. Tick the fields you want (description, city, price range, bedrooms, bathrooms, property type; all six by default) and choose whether the scope’s first listings show before anyone searches.
3. Copy the snippet and paste it where the search box should appear, the same way as step 4. If the page already has the script tag from another widget, you do not need it twice.

<div class="hs-embed"
     data-hs-embed="search"
     data-hs-key="hsx_live_yourbrokerage_7f3a9c2e"
     data-hs-scope="search"
     data-hs-fields="q,city,price,beds,type"
     data-hs-initial="scope"
     data-hs-limit="9"
     data-hs-columns="3"
     data-hs-heading-level="2"
     data-hs-fallback-href="https://search.yourbrokerage.com/search">
  <noscript><a href="https://search.yourbrokerage.com/search">Search listings</a></noscript>
</div>

The form’s controls are real form controls posting to your HomeStar search page, so submitting before the widget is ready still works. With scripts off, though, the form is never painted at all and the visitor sees only your <noscript>: put a working search form there rather than a link if your page already has one. With JavaScript, results load into the widget as the visitor changes a filter or presses Search, every set of results carries the MLS attribution, and a link under the cards opens the full search with the same filters. If results cannot be fetched, that link is what shows, with the visitor’s filters intact.

The attribute list and the exact form fields are in the Search widget section of the reference.

---

6. Know what the fallback looks like

If the listings cannot be fetched, time out, come back empty, or arrive without the MLS attribution, the mount shows a single text link instead of the grid: “Browse Hayden listings” (the <noscript> text, or “Browse listings” if there is none), pointing at data-hs-fallback-href. The reserved space collapses so there is no blank box.

If you see the fallback on a page that should have listings, check the preview URL from step 3 first. It answers “is it the scope or is it my page” in one load.

---

Keep the attribution visible

The attribution block under the cards is a licence requirement, not decoration. Do not hide, shrink or move it with your own CSS. A nightly check loads every page you registered in step 2 and fails if the block is missing, invisible, smaller than 12px, or smaller than the card text. The loader itself refuses to insert a fragment that lacks it.

Style the widget only through the data-hs-* attributes and the --hs-* custom properties. Class names and DOM structure inside the widget are internal and will change.