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
- Sign up for an account and get your App ID
- Add your website domain in Domains
- Use the widget builder to configure style and options
- Copy the generated embed code (iframe or JavaScript format)
- 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.
| Attribute | Type | Description |
|---|---|---|
data-school-id |
string (School ID) | School required |
Editable Options
| Attribute | Type | Default | Description |
|---|---|---|---|
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.
| Attribute | Type | Description |
|---|---|---|
data-district-id |
string (District ID) | District required |
Editable Options
| Attribute | Type | Default | Description |
|---|---|---|---|
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.
| Attribute | Type | Description |
|---|---|---|
data-school-id |
string (School ID) | School required |
Editable Options
| Attribute | Type | Default | Description |
|---|---|---|---|
data-style |
enum | badge |
Badge Style
|
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
| Attribute | Type | Default | Description |
|---|---|---|---|
data-search-mode |
enum | simple |
Search Mode
|
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
|
data-default-level |
enum | All Levels |
Default School Level
|
data-max-results |
enum | 100 |
Only applies to Full Address mode. ZIP/City mode returns all 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
|
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.
| Attribute | Type | Description |
|---|---|---|
data-school-id |
string (School ID) | Search for and select a school required |
Editable Options
| Attribute | Type | Default | Description |
|---|---|---|---|
data-chart-type |
enum | bar |
Chart Type
|
data-x-axis |
enum | subject |
X-Axis Data
|
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.
| Attribute | Type | Description |
|---|---|---|
data-district-id |
string (District ID) | Use district autocomplete to limit school results |
Editable Options
| Attribute | Type | Default | Description |
|---|---|---|---|
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
|
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
|
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
|
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
| Attribute | Type | Default | Description |
|---|---|---|---|
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
|
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
|
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.
| Attribute | Type | Description |
|---|---|---|
data-state |
string (2-letter state code) | Two-letter state code (e.g., CA, NY, TX) required |
Editable Options
| Attribute | Type | Default | Description |
|---|---|---|---|
data-level |
enum | Elementary |
Filter by school level
|
data-count |
enum | 10 |
Number of schools to display
|
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
|
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.
| Attribute | Type | Description |
|---|---|---|
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
| Attribute | Type | Default | Description |
|---|---|---|---|
data-center-mode |
enum | school |
How to determine the center of the map
|
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
|
data-level |
enum | All Levels |
Filter schools by level
|
data-max-results |
enum | 50 |
Maximum number of schools to display
|
data-map-provider |
enum | openstreetmap |
Map tile provider
|
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)
|
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
|
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:
| Property | Type | Default | Description |
|---|---|---|---|
primaryColor | hex color | #1a73e8 | Main widget accent color |
fontFamily | CSS font stack | system-ui | Font family for widget text |
fontSize | enum | medium | small, medium, or large |
theme | enum | light | light or dark |
borderRadius | enum | medium | none, small, medium, or large |
showBranding | boolean | true | Show SchoolDigger attribution (Pro+ to disable) |
customCss | string | - | 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.