1build Widget Reference

Use the 1build widget to allow your users to browse our Cost Data database.

This integration is using a previously-generated test API key, which modifies the prices by random percentages. Get your own API key to start getting real live cost data.


The 1build widget is the client-side component that your users will interact with in order to get our Cost Data into their projects.

The widget will handle authentication, pagination, location and search for you.

Getting Started

Are you looking to use an external API key? Click here to get started with the API reference.

Include the 1build widget script on your app.

Note: If you need to include the script in the head component, be sure to add the async and defer attributes, since our widget depends on the body to fully load.

<script src="https://cdn.1build.com/widget.js"></script>

After including the script, a global object named onebuild will be available for you to manage the widget (see the API reference).

Keep in mind our widget uses lazy-loading for the queries that fetch the categories and the items, meaning, the widget won’t trigger any of those request unless you open the containing dropdown.


Access to the widget is authenticated by your API key which will need to be passed in the init method. API keys are unique to your organization and they come in two types:

Because the EMBEDDED key must be included in your client-side code it cannot be kept secret. For this reason you must configure referrers in your 1build organization preferences to match the domain name of the website hosting the code which will call the API. For example, if your application is hosted at https://constructionmagic.com/parts/lookup, you would put https://constructionmagic.com/ in your referrers list.

Be sure to use the widget with an EMBEDDED API key. If you need an API key or for help using one please contact help@1build.com.

API reference


The init method is used to initialize the widget with your own particular configuration. Ideally you would call this method right after your application loads, and only once for the lifetime of your app.



The API key provided by 1build.


An object to set the color palette and typography configuration.

The 1build widget uses Material UI component library to power its components and styles and this theme property is a sub-set of MUI’s own theme.

We know it’s difficult to understand the properties you can use without proper typing, we’re working on giving you the most up-to-date type definitions. We’ll keep this page updated with our progress.

You can also use this tool to play with your theme configuration.

Types reference

init(params: WidgetInitParams) ⇒ void
interface WidgetInitParams {
    // The API key provided by 1build.
    key: string
    // An object to set the color palette and typography configuration.
    theme?: {
        palette?: Record<string, unknown>
        typography?: Record<string, unknown>


The identify method allows you to pass a string that uniquely identifies the user who is performing the search. This is attached to the logged metrics and can improve usage analysis.


onebuild.identify({ userId: "YOUR_USER_ID" })


An arbitrary string that you use to identify the user of your system. This could be an email address, a UUID or any other unique identifier.

Types reference

identify(params: WidgetIdentifyParams) ⇒ void
interface WidgetIdentifyParams {
    userId: string


The open method allows you to open the widget when the user is ready to search the cost data.



A boolean indicating if the widget should close when a rate is selected. Defaults to true.


A boolean indicating if the search should use ‘typeahead’ or not. In case of true a ‘search’ button will be shown and the search will be performed only when that button is clicked. Defaults to false.


A type of item to filter by inside the widget. Defaults to ‘all items’.

The possible values are:


A pre-defined search location in state and county or coordinates or zipcode.

The 1build data is county-based, so the coordinate and zipcode inputs are used to find the closest county.


A callback that is executed when a rate is successfully selected.

This callback is called with an object containing 3 properties:


The maximum number of sources per category to be returned in every search. For the top results the default value is 5, for the categories the default value is 20.


A boolean indicating if the search location is read-only or not. Defaults to false.


A boolean indicating if the widget will request the location from the browser. Defaults to false.


A pre-defined search term.


A type of configuration based on which sources will be retrieved from our cost data database. You can specify one general configuration or one configuration per page.

Note: this configuration may affect your billed rate.

As mentioned, you can also pass an object with the following shape:

    searchPage: SourceRequestConfigType
    detailsPage: SourceRequestConfigType



Time in milliseconds before another search gets triggered by the search input.

Types reference

open(params: WidgetOpenParams) ⇒ void
interface WidgetOpenParams {
    // closeOnRateSelected defaults to true
    closeOnRateSelected?: boolean
    // disableTypeahead defaults to false
    disableTypeahead?: boolean
    // filter defaults to `ALL`
    filter?: SourceType
        | {
              lat: string
              lng: string
              state: never
              county: never
              zipcode: never
        | {
              lat: never
              lng: never
              state: string
              county: string
              zipcode: never
        | {
              lat: never
              lng: never
              state: never
              county: never
              zipcode: string

    onRateSelected?: (args: OnRateSelectedArgs) => void
    pageLimit?: number
    // readOnlyLocation defaults to false
    readOnlyLocation?: boolean
    // requestBrowserLocation defaults to false
    requestBrowserLocation?: boolean
    searchTerm?: string
    // sourceRequestConfig defaults to SourceRequestConfigType.DETAIL
        | SourceRequestConfigType
        | {
              searchPage: SourceRequestConfigType
              detailsPage: SourceRequestConfigType
    // topResultsBehavior defaults to "OPEN"
    topResultsBehavior?: "OPEN" | "CLOSED" | "HIDDEN"

enum SourceRequestConfigType {
    BASE = "BASE",

interface OnRateSelectedArgs {
    // This type will change based on the `sourceRequestConfig` value
    source: Source
    // selectedRate.calculatedUnitRateUsdCents has the rate selected by user in the widget
    // selectedRate.uom has the unit of measure the selected by user in the widget
    selectedRate: KnownUom
    selectedLaborRateType: "BASE" | "BURDENED" | undefined

Please refer to the 1build API reference for the following types:


The on method will create an event listener. You can create as many listeners as you want.

Currently it supports these events:


// file1.js
onebuild.on("request", (args) => calculation1(args))

// file2.js
onebuild.on("request", (args) => calculation2(args))

Types reference

on(eventName: ListenerEventName, callback: (args: unknown) => unknown) ⇒ void

enum ListenerEventName {
    Request = "request",


The off method will remove a previously-created event listener.



Types reference

off(eventName: ListenerEventName) ⇒ void

enum ListenerEventName {
    Request = "request",


The close method will close the widget.



Types reference

close() ⇒ void