Theming

Embedded Residently views can be customised to blend in with the look and feel of your site. Use the theme option to override colours, typography, layout, and optional UI features so the embed feels native to your brand.

Pass a theme object when instantiating the Residently client — it is then applied to every view rendered by that instance. Sections that don't apply to a particular view (for example, the property grid layout on the listing detail view) are simply ignored, so it's safe to share a single theme object across every embed on your site.

All colour properties accept any valid CSS colour value (hex, rgb(), hsl(), named colours, etc.). All properties on the theme object are optional — omit anything you're happy to leave at the default.

Most sections of the theme object group style keys (e.g. property.card, availability.background, filters.button) that each accept any CSS property in camelCase (e.g. backgroundColor, color, borderRadius, padding, fontWeight). Values are passed through as inline styles on the corresponding element, so use whatever CSS you'd normally write. A small number of properties are flags or layout values rather than style objects (e.g. columns, enabled, font) — those are documented explicitly below.

Example

import Residently from "@residently/embed-sdk";

const residently = new Residently({
  theme: {
    columns: 3,
    backgroundColor: "#ffffff",
    property: {
      card: {
        backgroundColor: "#f8f8f8",
        borderRadius: "8px",
        padding: "16px",
      },
      title: {
        color: "#1a1a1a",
        fontWeight: "600",
        fontSize: "1.125rem",
      },
      body: {
        color: "#555555",
        fontWeight: "400",
        lineHeight: "1.5",
      },
    },
    availability: {
      enabled: true,
      background: {
        backgroundColor: "#e8f5e9",
        borderRadius: "4px",
      },
      text: {
        color: "#2e7d32",
        fontWeight: "600",
      },
    },
    font: {
      url: "https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap",
      family: "Inter, sans-serif",
      baseSizePx: 16,
    },
    compare: {
      enabled: true,
    },
    filters: {
      enabled: true,
      background: {
        backgroundColor: "#f0f0f0",
        padding: "8px",
      },
      button: {
        backgroundColor: "#ffffff",
        borderRadius: "4px",
      },
      buttonText: {
        color: "#333333",
        fontWeight: "500",
      },
      buttonHover: {
        backgroundColor: "#e0e0e0",
      },
      buttonHoverText: {
        color: "#111111",
      },
      menu: {
        backgroundColor: "#ffffff",
        borderRadius: "4px",
      },
      menuText: {
        color: "#333333",
      },
      menuTextHighlight: {
        color: "#1a73e8",
        fontWeight: "600",
      },
    },
  },
});

residently.embedView("collection", {
  container: document.getElementById("listings"),
  collectionToken: "provided_by_residently",
});

Layout

Property	Type	Default	Description
columns	number	3	Number of property cards per grid row. Accepts 2, 3, or 4. Applies to the listing collection view only.

Colours

Property	Type	Default	Description
backgroundColor	string	—	Main background colour of the embedded view. Accepts any valid CSS colour value.

property object

Customise individual property cards. Applies to the listing collection view only.

Each style key below accepts an object of any CSS properties in camelCase, applied as inline styles to the corresponding element.

Property	Type	Default	Description
card	object	—	Styles applied to each property card container.
title	object	—	Styles applied to the property title text.
body	object	—	Styles applied to the property body text (price, address, etc.).

property: {
  card: {
    backgroundColor: "#f8f8f8",
    borderRadius: "8px",
    padding: "16px",
    boxShadow: "0 1px 3px rgba(0, 0, 0, 0.1)",
  },
  title: {
    color: "#1a1a1a",
    fontWeight: "600",
    fontSize: "1.125rem",
  },
  body: {
    color: "#555555",
    fontWeight: "400",
    lineHeight: "1.5",
  },
}

availability object

Controls the availability badge displayed on each property card.

Property	Type	Default	Description
enabled	boolean	true	Show or hide the property availability badge.
background	object	—	Styles applied to the badge container. Accepts any CSS property in camelCase.
text	object	—	Styles applied to the badge text. Accepts any CSS property in camelCase.

availability: {
  enabled: true,
  background: {
    backgroundColor: "#e8f5e9",
    borderRadius: "4px",
  },
  text: {
    color: "#2e7d32",
    fontWeight: "600",
  },
}

font object

Load a custom font into the embedded view.

Property	Type	Default	Description
url	string	—	URL of a CSS stylesheet that declares your @font-face rules (e.g. a Google Fonts URL).
family	string	—	The CSS font-family value to apply globally (e.g. "Inter, sans-serif").
baseSizePx	number	16	Base HTML font size in pixels. All rem values inside the embed scale relative to this.

compare object

Applies to the listing collection view only.

Property	Type	Default	Description
enabled	boolean	true	Enable the side-by-side property comparison feature.

filters object

Controls the filter bar displayed above the listing grid. Applies to the listing collection view only.

Each style key below accepts an object of any CSS properties in camelCase, applied as inline styles to the corresponding element.

Property	Type	Default	Description
enabled	boolean	true	Show or hide the filter bar.
background	object	—	Styles applied to the filter bar row.
button	object	—	Styles applied to filter buttons.
buttonText	object	—	Styles applied to filter button text.
buttonHover	object	—	Styles applied to filter buttons on hover.
buttonHoverText	object	—	Styles applied to filter button text on hover.
menu	object	—	Styles applied to the filter dropdown menu.
menuText	object	—	Styles applied to filter menu item text.
menuTextHighlight	object	—	Styles applied to the highlighted/hovered menu item text.

filters: {
  enabled: true,
  background: {
    backgroundColor: "#f0f0f0",
    padding: "8px",
  },
  button: {
    backgroundColor: "#ffffff",
    borderRadius: "4px",
  },
  buttonText: {
    color: "#333333",
    fontWeight: "500",
  },
  buttonHover: {
    backgroundColor: "#e0e0e0",
  },
  buttonHoverText: {
    color: "#111111",
  },
  menu: {
    backgroundColor: "#ffffff",
    borderRadius: "4px",
  },
  menuText: {
    color: "#333333",
  },
  menuTextHighlight: {
    color: "#1a73e8",
    fontWeight: "600",
  },
}