> ## Documentation Index
> Fetch the complete documentation index at: https://docs.letshum.com/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript Integration
> Step-by-step guide to integrate the Hum widget into your website using JavaScript and HTML
# JavaScript Widget Integration
The Hum widget can be embedded directly into your website with just a few lines of JavaScript and HTML. This integration method is ideal for web applications, landing pages, and any environment where you have control over the HTML and JavaScript.
This guide covers the JavaScript/HTML embed integration. For mobile app WebView integration, see [WebView Integration](/widget-integration/webview).
To test with a Sandbox key, load the Sandbox widget bundle instead of the Production bundle shown below. See [Environments and API Keys](/environments#widget-environments).
## Quick Start
Get up and running with the Hum widget in three simple steps:
Add a container div where you want the widget to render:
```html theme={null}
```
You can customize the container ID, but make sure it matches the element you pass to the widget constructor.
Load the Hum widget script in your HTML page:
```html theme={null}
```
The script loads asynchronously and is hosted on a CDN for optimal performance.
Initialize the widget with your API key:
```javascript theme={null}
const hum = new HUM(
'YOUR_API_KEY_HERE',
document.getElementById('hum-widget')
);
hum.initialize();
// Store the instance globally for access by other components
window.humInstance = hum;
```
Verify the widget loads by checking your browser's developer console for any error messages.
## Configuration
The Hum widget accepts an optional configuration object as the third parameter. For a complete list of available options, see the [Widget Overview](/widget-integration/overview#configuration-options).
### Basic Configuration Example
```javascript theme={null}
const hum = new HUM(
'YOUR_API_KEY_HERE',
document.getElementById('hum-widget'),
{
resultLayout: 'checkout',
primaryColor: '#1274f9',
campaignId: 'Q4-2024-campaign'
}
);
hum.initialize();
```
### Advanced Configuration Example
Here's an example with all available options:
```javascript theme={null}
const hum = new HUM(
'YOUR_API_KEY',
document.getElementById('hum-widget'),
{
// Display & Layout
resultLayout: 'checkout',
primaryColor: '#1274f9',
showSavePlanButton: true, // Enable save/unsave plan button
showAddressCompletionForm: false, // Let the widget collect the address itself
// Tracking & Analytics
campaignId: 'Q4-2024-landing-page',
// Filtering & Limiting
limitProviders: ['130077', '130317'],
primaryProviders: ['130077'],
limitTechnologies: ['Fiber', 'Cable', 'Wireless'],
// Customer Data Pre-population
customerData: {
firstName: 'Jane',
lastName: 'Smith',
email: 'jane.smith@example.com',
phoneNumber: '555-987-6543'
}
}
);
hum.initialize();
```
## Integration Examples
### Example 1: Form-Based Integration
Integrate the widget with an HTML form for address input:
A `campaign_id` field inside widget address data is ignored. Set campaign attribution with the widget's `campaignId` configuration option.
```html index.html theme={null}
Hum Widget Demo
```
Test your integration by entering a valid US address and verifying that service options load correctly.
### Example 2: Direct Address Loading
Load address data directly when you already have the information:
```html direct-integration.html theme={null}
Hum Widget - Direct Integration
```
Use direct integration when you already have address data from a previous form, user profile, or application state.
### Example 3: React Integration
Integrate the Hum widget into a React application:
```javascript HumWidget.jsx theme={null}
import React, { useEffect, useRef, useState } from 'react';
function HumWidget({ apiKey, addressData, config }) {
const containerRef = useRef(null);
const humInstanceRef = useRef(null);
const [isLoading, setIsLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
// Initialize widget
const initializeWidget = async () => {
try {
setIsLoading(true);
setError(null);
// Create HUM instance
const hum = new window.HUM(
apiKey,
containerRef.current,
config
);
await hum.initialize();
humInstanceRef.current = hum;
// Load address if provided
if (addressData) {
await hum.internetServiceFromAddress(addressData);
}
setIsLoading(false);
} catch (err) {
console.error('Failed to initialize Hum widget:', err);
setError(err.message);
setIsLoading(false);
}
};
if (containerRef.current) {
initializeWidget();
}
// Cleanup
return () => {
if (humInstanceRef.current) {
// Cleanup logic if needed
humInstanceRef.current = null;
}
};
}, [apiKey, addressData, config]);
// Method to update address
const updateAddress = async (newAddress) => {
if (humInstanceRef.current) {
try {
await humInstanceRef.current.internetServiceFromAddress(newAddress);
} catch (err) {
console.error('Failed to update address:', err);
setError(err.message);
}
}
};
if (error) {
return (
Error loading widget: {error}
);
}
return (
{isLoading &&
Loading widget...
}
Internet Service Finder
);
}
export default App;
```
### Example 4: Vue.js Integration
Integrate the widget into a Vue.js application:
```vue HumWidget.vue theme={null}
Loading widget...
{{ error }}
```
## Address Data Format
The widget expects address data in a specific JSON format:
```json theme={null}
{
"street1": "1001 Woodward Ave",
"street2": "Suite 500",
"city": "Detroit",
"state": "MI",
"zip": "48226",
"latitude": 42.3317,
"longitude": -83.0479
}
```
For complete field specifications, see the [Address Data Format](/widget-integration/overview#address-data-format) section in the overview.
## Address Validation
The widget validates addresses using these rules:
* **street1**: Primary address (street number and name)
* **zip**: 5 or 9-digit ZIP code format (12345 or 12345-6789)
* **street2**: Unit/apartment information (no specific format required)
* **city**: City name (recommended for improved address match quality)
* **state**: 2-letter US state code (recommended for improved address match quality)
* **latitude/longitude**: Must be provided together and within US territorial bounds
* Address must be geocodable by our system
* Address must be serviceable by at least one provider
* Coordinates must be within the bounds of the US and its territories
## Troubleshooting
**Check these common issues:**
* Verify the container div exists on the page
* Ensure the widget script loads before your initialization code
* Check that your API key is valid and properly formatted
* Look for JavaScript errors in the browser console
**Expected behavior:** The widget should initialize within 2-3 seconds of calling `hum.initialize()`.
**Common address issues:**
* Ensure the required fields (`street1` and `zip`) are provided
* Include `city` and `state` when available to improve address match quality
* Verify the state is a valid 2-letter US state code
* Check that the ZIP code is in the correct format (12345 or 12345-6789)
* Make sure the address is a real, serviceable US address
**Expected behavior:** Valid addresses should return service options within 5-10 seconds.
**Optimization tips:**
* Include latitude and longitude coordinates when available
* Use the summary layout for faster loading when full e-commerce isn't needed
* Ensure the widget script is loaded asynchronously
* Check network connectivity and CDN availability
**Expected behavior:** The widget should load service options in under 10 seconds for most addresses.
**Common integration issues:**
* Verify the widget instance is stored globally if accessed by other scripts
* Check for conflicts with other JavaScript libraries
* Ensure proper error handling for failed API calls
* Verify the container element is visible and properly sized
**Expected behavior:** The widget should integrate seamlessly without affecting other page functionality.
If issues persist, check the browser console for detailed error messages and contact support with the specific error details.
## Best Practices
Always implement proper error handling for API calls:
```javascript theme={null}
hum.initialize()
.then(() => console.log('Success'))
.catch(error => {
console.error('Error:', error);
// Show user-friendly error message
});
```
Use loading states to improve user experience:
```javascript theme={null}
button.textContent = 'Loading...';
button.disabled = true;
try {
await hum.internetServiceFromAddress(addressData);
} finally {
button.textContent = 'Check Availability';
button.disabled = false;
}
```
* Load the widget script asynchronously
* Include latitude/longitude coordinates for faster results
* Cache widget instances when using multiple widgets
* Monitor console logs during development
* Test with various address formats and edge cases
* Provide clear error messages
* Use appropriate layouts for your use case
* Include campaign IDs for better tracking
## Next Steps
Learn how to listen for and handle events from the widget
Explore all available configuration parameters
Integrate the widget into mobile applications
Contact our team for integration assistance