Widget Documentation

Embed code reference for SchoolDigger widgets. Use the widget builder to generate embed code, then customize the data attributes described here.

Overview

SchoolDigger widgets are configured with two types of attributes:

  • data-config (optional) — A Base64-encoded JSON blob containing style options (colors, fonts, theme, branding, sizing). Generated by the widget builder. If omitted, sensible defaults are used (light theme, medium font size, default colors). You typically don't edit this directly.
  • data-* attributes — Plain-text HTML attributes for all functional options (which school, what to show/hide, search defaults, etc.). These are easy to read and modify directly in your embed code.

This separation means you can change what a widget displays — switch schools, toggle features, change filter defaults — by editing the data attributes, without touching the style blob. You can also skip data-config entirely and just use data attributes with the default styling.

Quick Start

  1. Sign up for an account and get your App ID
  2. Add your website domain in Domains
  3. Use the widget builder to configure style and options
  4. Copy the generated embed code (iframe or JavaScript format)
  5. Paste into your HTML and customize the data-* attributes as needed

Configuration Layers

Embed Formats

JavaScript embed (recommended) — uses a container <div> with data attributes + the widget loader script:

<!-- Full example with custom styling --> <div id="sd-widget-340576000472" data-sd-widget="school-info-card" data-config="eyJ3aWRn...base64..." data-school-id="340576000472" data-show-address="true" data-show-ranking="true"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal example — default styling, just data attributes --> <div data-sd-widget="school-info-card" data-school-id="340576000472"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

Iframe embed — uses the same options as URL query parameters:

<!-- Full example with custom styling --> <iframe src="https://widgets.schooldigger.com/embed/school-info-card?config=eyJ3aWRn...&appID=YOUR_APP_ID&schoolId=340576000472&showAddress=true&showRanking=true" width="350" height="200" frameborder="0" title="SchoolDigger Widget"> </iframe> <!-- Minimal example — default styling --> <iframe src="https://widgets.schooldigger.com/embed/school-info-card?appID=YOUR_APP_ID&schoolId=340576000472" width="350" height="200" frameborder="0" title="SchoolDigger Widget"> </iframe>

Boolean Values

Boolean data attributes accept the strings "true" or "false". Example: data-show-address="false" hides the address.

Attribute Naming

Data attributes use kebab-case (e.g., data-show-address). In iframe query parameters, use camelCase (e.g., showAddress).

Widget Reference

Each widget's configurable options are listed below. The data-config attribute is optional — if omitted, default styling is used. Use the widget builder to generate it, or just use data attributes with the defaults.

School Information Card Free+ School Profile

Display basic school information in a compact card format.

Default size: 350px × 200px (responsive)

Required Selections (set in builder)

These are configured via the widget builder UI and included as data attributes in the generated embed code.

AttributeTypeDescription
data-school-id string (School ID) School required

Editable Options

AttributeTypeDefaultDescription
data-show-address boolean True Show Address
data-show-phone boolean True Show Phone
data-show-grades boolean True Show Grade Levels
data-show-ranking boolean True Show Ranking Basic+

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="school-info-card" data-config="{style-config}" data-school-id="SCHOOL_ID" data-show-address="True" data-show-phone="True" data-show-grades="True" data-show-ranking="True"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="school-info-card" data-school-id="SCHOOL_ID" data-show-address="True" data-show-phone="True" data-show-grades="True" data-show-ranking="True"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

District Information Card Free+ District Profile

Display basic district information in a compact card format.

Default size: 350px × 220px (responsive)

Required Selections (set in builder)

These are configured via the widget builder UI and included as data attributes in the generated embed code.

AttributeTypeDescription
data-district-id string (District ID) District required

Editable Options

AttributeTypeDefaultDescription
data-show-address boolean True Show Address
data-show-phone boolean True Show Phone
data-show-grades boolean True Show Grade Levels
data-show-school-counts boolean True Show School Counts
data-show-ranking boolean True Show Ranking Basic+

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="district-info-card" data-config="{style-config}" data-district-id="DISTRICT_ID" data-show-address="True" data-show-phone="True" data-show-grades="True" data-show-school-counts="True" data-show-ranking="True"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="district-info-card" data-district-id="DISTRICT_ID" data-show-address="True" data-show-phone="True" data-show-grades="True" data-show-school-counts="True" data-show-ranking="True"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

Ranking Badge Basic+ Rankings

Show school or district ranking with a visual indicator.

Default size: 150px × 80px (responsive)

Required Selections (set in builder)

These are configured via the widget builder UI and included as data attributes in the generated embed code.

AttributeTypeDescription
data-school-id string (School ID) School required

Editable Options

AttributeTypeDefaultDescription
data-style enum badge Badge Style
  • badge — Badge
  • ribbon — Ribbon
  • minimal — Minimal
data-show-state-context boolean True Show State Context

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="ranking-badge" data-config="{style-config}" data-school-id="SCHOOL_ID" data-style="badge" data-show-state-context="True"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="ranking-badge" data-school-id="SCHOOL_ID" data-style="badge" data-show-state-context="True"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

School Finder Basic+ Search

Interactive search widget to find schools by ZIP code, city, or full address.

Default size: 450px × 500px (responsive)

Editable Options

AttributeTypeDefaultDescription
data-search-mode enum simple Search Mode
  • simple — ZIP Code or City (exact match)
  • address — Full Address (radius search)
data-initial-state string - Two-letter state code to pre-fill (e.g., CA, NY, TX). Required at search time.
data-initial-zip string - Pre-fill with ZIP code
data-initial-city string - Pre-fill with city name
data-initial-street string - Pre-fill with street address (for full address mode)
data-default-radius enum 10 Only applies to Full Address mode
  • 5 — 5 miles
  • 10 — 10 miles
  • 15 — 15 miles
  • 25 — 25 miles
  • 50 — 50 miles
data-default-level enum All Levels Default School Level
  • (omit) — All Levels
  • Elementary — Elementary
  • Middle — Middle
  • High — High
  • Alt — Alternative
  • Public — Public
  • Private — Private
data-max-results enum 100 Only applies to Full Address mode. ZIP/City mode returns all schools.
  • 5 — 5 schools
  • 10 — 10 schools
  • 15 — 15 schools
  • 20 — 20 schools
  • 50 — 50 schools
  • 100 — 100 schools
data-max-height string 500 Maximum height of results area in pixels
data-allow-auto-expand boolean True When enabled, results expand inline with 'View all' button. When disabled, results scroll within max height.
data-show-rankings boolean True Show Rankings
data-show-level-filter boolean True Show Level Filter
data-show-radius-filter boolean True Only shown in Full Address mode
data-on-school-click enum navigate What happens when a school is clicked
  • navigate — Open SchoolDigger page (new tab)
  • callback — Raise event only (for custom handling)

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="school-finder" data-config="{style-config}" data-search-mode="simple" data-default-radius="10" data-default-level="All Levels" data-max-results="100" data-max-height="500" data-allow-auto-expand="True" data-show-rankings="True" data-show-level-filter="True" data-show-radius-filter="True" data-on-school-click="navigate"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="school-finder" data-search-mode="simple" data-default-radius="10" data-default-level="All Levels" data-max-results="100" data-max-height="500" data-allow-auto-expand="True" data-show-rankings="True" data-show-level-filter="True" data-show-radius-filter="True" data-on-school-click="navigate"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

Test Score Chart Pro+ Test Scores

Visualize test score performance with configurable x-axis (subject, year, or grade).

Default size: 400px × 350px (responsive)

Required Selections (set in builder)

These are configured via the widget builder UI and included as data attributes in the generated embed code.

AttributeTypeDescription
data-school-id string (School ID) Search for and select a school required

Editable Options

AttributeTypeDefaultDescription
data-chart-type enum bar Chart Type
  • bar — Bar Chart
  • line — Line Chart
data-x-axis enum subject X-Axis Data
  • subject — Subject/Test
  • year — Year
  • grade — Grade
data-year string - Filter by year (when x-axis is not Year)
data-grade string - Filter by grade (when x-axis is not Grade)
data-subject string - Filter by subject (when x-axis is not Subject)
data-show-filters boolean True Show Filters
data-show-district-average boolean True Show District Scores
data-show-state-average boolean True Show State Scores

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="test-score-chart" data-config="{style-config}" data-school-id="SCHOOL_ID" data-chart-type="bar" data-x-axis="subject" data-show-filters="True" data-show-district-average="True" data-show-state-average="True"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="test-score-chart" data-school-id="SCHOOL_ID" data-chart-type="bar" data-x-axis="subject" data-show-filters="True" data-show-district-average="True" data-show-state-average="True"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

School Autocomplete Basic+ Search

A searchable autocomplete widget for finding and selecting schools. Shows school name, city/state, and grade levels.

Default size: 400px × 60px (responsive)

Required Selections (set in builder)

These are configured via the widget builder UI and included as data attributes in the generated embed code.

AttributeTypeDescription
data-district-id string (District ID) Use district autocomplete to limit school results

Editable Options

AttributeTypeDefaultDescription
data-placeholder string Search for a school... Text shown when input is empty
data-default-level enum All Levels Limit search to specific school level
  • (omit) — All Levels
  • Elementary — Elementary
  • Middle — Middle
  • High — High
  • Alt — Alternative
  • Private — Private
data-default-state string - Two-letter state code to limit results (e.g., CA, NY)
data-search-city-state-name boolean True Search by city name in addition to school name (disabled when limited to a district)
data-max-results enum 10 Max Results
  • 5 — 5 results
  • 10 — 10 results
  • 15 — 15 results
  • 20 — 20 results
data-show-grades boolean True Show Grade Levels
data-show-location boolean True Show City/State
data-on-select-action enum callback What happens when a school is selected
  • callback — JavaScript Callback
  • navigate — Navigate to SchoolDigger

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="school-autocomplete" data-config="{style-config}" data-placeholder="Search for a school..." data-default-level="All Levels" data-search-city-state-name="True" data-max-results="10" data-show-grades="True" data-show-location="True" data-on-select-action="callback"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="school-autocomplete" data-placeholder="Search for a school..." data-default-level="All Levels" data-search-city-state-name="True" data-max-results="10" data-show-grades="True" data-show-location="True" data-on-select-action="callback"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

District Autocomplete Basic+ Search

A searchable autocomplete widget for finding and selecting school districts. Shows district name, city/state, and grade levels.

Default size: 400px × 60px (responsive)

Editable Options

AttributeTypeDefaultDescription
data-placeholder string Search for a district... Text shown when input is empty
data-default-state string - Two-letter state code to limit results (e.g., CA, NY)
data-max-results enum 10 Max Results
  • 5 — 5 results
  • 10 — 10 results
  • 15 — 15 results
  • 20 — 20 results
data-show-grades boolean True Show Grade Levels
data-show-location boolean True Show City/State
data-on-select-action enum callback What happens when a district is selected
  • callback — JavaScript Callback
  • navigate — Navigate to SchoolDigger

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="district-autocomplete" data-config="{style-config}" data-placeholder="Search for a district..." data-max-results="10" data-show-grades="True" data-show-location="True" data-on-select-action="callback"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="district-autocomplete" data-placeholder="Search for a district..." data-max-results="10" data-show-grades="True" data-show-location="True" data-on-select-action="callback"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

Top Schools List Basic+ Rankings

Display a list of the top-ranked schools in a state, with optional filtering by school level.

Default size: 400px × 450px (responsive)

Required Selections (set in builder)

These are configured via the widget builder UI and included as data attributes in the generated embed code.

AttributeTypeDescription
data-state string (2-letter state code) Two-letter state code (e.g., CA, NY, TX) required

Editable Options

AttributeTypeDefaultDescription
data-level enum Elementary Filter by school level
  • Elementary — Elementary
  • Middle — Middle
  • High — High
data-count enum 10 Number of schools to display
  • 5 — Top 5
  • 10 — Top 10
  • 15 — Top 15
  • 20 — Top 20
  • 25 — Top 25
data-show-stars boolean True Show Star Ratings
data-show-location boolean True Show City/State
data-show-percentage boolean False Show Rank Percentage
data-max-height string 400 Maximum height of results area in pixels
data-on-school-click enum navigate What happens when a school is clicked
  • navigate — Open SchoolDigger page (new tab)
  • callback — Raise event only (for custom handling)

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="top-schools-list" data-config="{style-config}" data-state="CA" data-level="Elementary" data-count="10" data-show-stars="True" data-show-location="True" data-show-percentage="False" data-max-height="400" data-on-school-click="navigate"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="top-schools-list" data-state="CA" data-level="Elementary" data-count="10" data-show-stars="True" data-show-location="True" data-show-percentage="False" data-max-height="400" data-on-school-click="navigate"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

Nearby Schools Map Pro+ Maps

Interactive map displaying schools near a location or around a specific school. Uses OpenStreetMap (free) or Mapbox (requires your API key).

Default size: 500px × 400px (responsive)

Required Selections (set in builder)

These are configured via the widget builder UI and included as data attributes in the generated embed code.

AttributeTypeDescription
data-school-id string (School ID) School to center the map on (for 'Specific School' mode)
data-center-state string (2-letter state code) State for the search (required for API calls)

Editable Options

AttributeTypeDefaultDescription
data-center-mode enum school How to determine the center of the map
  • school — Specific School
  • address — Full Address
  • latlong — Latitude/Longitude
data-center-address string - Full address to center the map on (for 'Address' mode)
data-center-latitude string - Latitude coordinate (for 'Latitude/Longitude' mode, e.g., 47.6062)
data-center-longitude string - Longitude coordinate (for 'Latitude/Longitude' mode, e.g., -122.3321)
data-radius-miles enum 5 Radius for initial school search
  • 1 — 1 mile
  • 2 — 2 miles
  • 5 — 5 miles
  • 10 — 10 miles
  • 15 — 15 miles
  • 25 — 25 miles
data-level enum All Levels Filter schools by level
  • (omit) — All Levels
  • Elementary — Elementary
  • Middle — Middle
  • High — High
  • Private — Private
data-max-results enum 50 Maximum number of schools to display
  • 10 — 10 schools
  • 25 — 25 schools
  • 50 — 50 schools
  • 100 — 100 schools
data-map-provider enum openstreetmap Map tile provider
  • openstreetmap — OpenStreetMap (free, no key required)
  • mapbox — Mapbox (requires your API key)
data-map-api-key string - Your Mapbox API key (required if using Mapbox)
data-zoom-level enum 12 Initial zoom level (higher = more zoomed in)
  • 10 — 10 - City level
  • 11 — 11
  • 12 — 12 - Neighborhood (default)
  • 13 — 13
  • 14 — 14 - Streets
  • 15 — 15 - Close up
data-show-zoom-controls boolean True Show Zoom Controls
data-is-interactive boolean True Allow users to pan and zoom the map
data-reload-on-move boolean False Fetch new schools when the map view changes (requires Interactive Map)
data-highlight-center-school boolean True Show the center school with a different marker color
data-show-stars-in-popup boolean True Show Stars in Popup
data-show-address-in-popup boolean True Show Address in Popup
data-show-grades-in-popup boolean True Show Grades in Popup
data-show-level-in-popup boolean True Show Level in Popup
data-on-school-click enum navigate What happens when a school is clicked in the popup
  • navigate — Open SchoolDigger page (new tab)
  • callback — Raise event only (for custom handling)

Example (JavaScript embed)

<div id="sd-widget" data-sd-widget="nearby-schools-map" data-config="{style-config}" data-school-id="SCHOOL_ID" data-center-mode="school" data-radius-miles="5" data-level="All Levels" data-max-results="50" data-map-provider="openstreetmap" data-zoom-level="12" data-show-zoom-controls="True" data-is-interactive="True" data-reload-on-move="False" data-highlight-center-school="True" data-show-stars-in-popup="True" data-show-address-in-popup="True" data-show-grades-in-popup="True" data-show-level-in-popup="True" data-on-school-click="navigate"> </div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script> <!-- Minimal (default styling) --> <div data-sd-widget="nearby-schools-map" data-school-id="SCHOOL_ID" data-center-mode="school" data-radius-miles="5" data-level="All Levels" data-max-results="50" data-map-provider="openstreetmap" data-zoom-level="12" data-show-zoom-controls="True" data-is-interactive="True" data-reload-on-move="False" data-highlight-center-school="True" data-show-stars-in-popup="True" data-show-address-in-popup="True" data-show-grades-in-popup="True" data-show-level-in-popup="True" data-on-school-click="navigate"></div> <script src="https://widgets.schooldigger.com/js/widget-loader.js?appID=YOUR_APP_ID" async></script>

Style Options (data-config)

These options are encoded in the data-config Base64 blob and are generated by the widget builder. The data-config attribute is optional — if omitted, the defaults below are used. You don't normally edit this manually, but here's what's inside:

PropertyTypeDefaultDescription
primaryColorhex color#1a73e8Main widget accent color
fontFamilyCSS font stacksystem-uiFont family for widget text
fontSizeenummediumsmall, medium, or large
themeenumlightlight or dark
borderRadiusenummediumnone, small, medium, or large
showBrandingbooleantrueShow SchoolDigger attribution (Pro+ to disable)
customCssstring-Custom CSS rules (Pro+ tier). See the CSS class reference.

Callback Events

Widgets that support the callback action mode communicate via window.postMessage. Listen for these events on the parent page:

School Clicked (school-finder, top-schools-list, nearby-schools-map)

Fired when a user clicks a school in a list or map popup (when data-on-school-click="callback").

window.addEventListener('message', function(event) { if (event.data.type === 'sd-school-clicked') { const school = event.data.school; console.log(school.schoolName, school.schoolId); // school: { schoolId, schoolName, city, state, zip, // schoolLevel, lowGrade, highGrade, // rank, rankStars, distance, url } } });

School Selected (school-autocomplete)

Fired when a user selects a school from the autocomplete dropdown (when data-on-select-action="callback").

window.addEventListener('message', function(event) { if (event.data.type === 'sd-school-selected') { const school = event.data.school; console.log(school.schoolName, school.schoolId); // school: { schoolId, schoolName, city, state, // lowGrade, highGrade, schoolLevel, rankStars } } });

School Cleared (school-autocomplete)

window.addEventListener('message', function(event) { if (event.data.type === 'sd-school-cleared') { console.log('School selection cleared'); } });

District Selected (district-autocomplete)

Fired when a user selects a district (when data-on-select-action="callback").

window.addEventListener('message', function(event) { if (event.data.type === 'sd-district-selected') { const district = event.data.district; console.log(district.districtName, district.districtId); // district: { districtId, districtName, city, state, // lowGrade, highGrade, rankStars } } });

District Cleared (district-autocomplete)

window.addEventListener('message', function(event) { if (event.data.type === 'sd-district-cleared') { console.log('District selection cleared'); } });

Widget Resize

Automatically handled by the widget loader. If you need to listen for size changes:

window.addEventListener('message', function(event) { if (event.data.type === 'sd-widget-resize') { console.log('New height:', event.data.height); } });

Custom CSS (Pro+)

Pro and Enterprise tier users can inject custom CSS rules to fine-tune widget styling. Add your CSS in the Custom CSS textarea in the widget builder, or include it in the customCss property of the data-config JSON blob.

Your CSS is injected inside the widget's <style> block, so rules apply within the widget iframe and won't affect your host page.

/* Example: change the school card border and title color */ .sd-school-card { border: 2px solid #ff5722; } .sd-school-name { color: #1a73e8; }

For a full list of CSS class names available in each widget, see the CSS Class Reference Guide.


Need help? Contact us or use the widget builder to generate embed code with your preferred settings.