This library was designed to be flexible and allow total customization of the markup used by all components.
There are two ways to replace the Handlebars template used by a component:
Pass a template HTML string containing a Handlebars template.
Pass the ID of a template element containing a Handlebars template.
Note: To avoid conflicts with BigCommerce and other systems that Handlebars for server-side rendering, this library also supports an alternate [[value]] syntax to work the same as the default Handlerbars {{value}} syntax.
In your HTML file, add the custom markup to either a script element with type attribute set to text/x-handlebars-template or a template element and pass the ID in the configuration options:
Note: script elements are preferred over template elements as they prevent some browser parsing behavior which can conflict with Handlebars directives in some edge cases.
Note: This approach tends to be easier to manage than the previous option as it is more compatible with popular HTML editors and templates can potentially be loaded from separate files using Server-side Includes (SSI).
By default, a neutral interface is rendered to get your search instance up and running quickly. However, this library was designed to be customizable and allow developers to use both custom markup and custom CSS.
For developers who only wish to tweak the default UI rather than create something from scratch, there are some variables and utility methods defined in the default CSS that are available for use.
Although all components in this library utilize the Shadow DOM, CSS variables are able to cross this boundary in a way that normal CSS rules are not. The following variables can be customized in the host DOM to easily customize some of the default styles:
Variable
Default Value
--hawksearch-container-background--alternate
var(--color-secondary-light)
--hawksearch-container-border
solid 1px var(--color-secondary)
--hawksearch-default-line-height
1.25
--hawksearch-default-font-color
#333333
--hawksearch-default-font-color--inverse
#ffffff
--hawksearch-default-font-family
Arial, sans-serif
--hawksearch-default-font-size
16px
--hawksearch-button-background
var(--color-accent)
--hawksearch-button-border-radius
5px
--hawksearch-button-font-color
#ffffff
--hawksearch-form-element-background
var(--color-background)
--hawksearch-form-element-border
solid 1px var(--color-secondary)
--hawksearch-form-element-border--focus
solid 1px var(--color-accent)
--hawksearch-form-element-border-radius
0
--hawksearch-form-element-placeholder-color
var(--color-secondary-dark)
--hawksearch-margin
32px
--hawksearch-margin-sm
calc(var(--margin) / 2)
--hawksearch-padding
24px
--hawksearch-padding-xs
calc(var(--padding) / 4)
--hawksearch-padding-sm
calc(var(--padding) / 2)
--hawksearch-secondary-font-color
var(--color-secondary-dark)
Note: Internally, all variables omit the hawksearch- prefix. This prefix is used only to override the default values.
This library uses a 12-column, responsive grid system. To use this system, all columns must have a column class and be the direct children of an element with a row class. The number of columns each column elements spans can be controlled with column--XX classes.
For example, the following will render two equal columns that are stacked until the browser window reaches the Medium breakpoint:
Overriding Component Templates
This library was designed to be flexible and allow total customization of the markup used by all components.
There are two ways to replace the Handlebars template used by a component:
Note: To avoid conflicts with BigCommerce and other systems that Handlebars for server-side rendering, this library also supports an alternate
[[value]]
syntax to work the same as the default Handlerbars{{value}}
syntax.Passing an HTML string
In your HTML file, define the template content directly in the configuration options:
Creating a script or template element
In your HTML file, add the custom markup to either a
script
element withtype
attribute set totext/x-handlebars-template
or atemplate
element and pass the ID in the configuration options:script
elements are preferred overtemplate
elements as they prevent some browser parsing behavior which can conflict with Handlebars directives in some edge cases.Note: This approach tends to be easier to manage than the previous option as it is more compatible with popular HTML editors and templates can potentially be loaded from separate files using Server-side Includes (SSI).
Customizing CSS
By default, a neutral interface is rendered to get your search instance up and running quickly. However, this library was designed to be customizable and allow developers to use both custom markup and custom CSS.
For developers who only wish to tweak the default UI rather than create something from scratch, there are some variables and utility methods defined in the default CSS that are available for use.
Variables
Although all components in this library utilize the Shadow DOM, CSS variables are able to cross this boundary in a way that normal CSS rules are not. The following variables can be customized in the host DOM to easily customize some of the default styles:
var(--color-secondary-light)
solid 1px var(--color-secondary)
1.25
#333333
#ffffff
Arial, sans-serif
16px
var(--color-accent)
5px
#ffffff
var(--color-background)
solid 1px var(--color-secondary)
solid 1px var(--color-accent)
0
var(--color-secondary-dark)
32px
calc(var(--margin) / 2)
24px
calc(var(--padding) / 4)
calc(var(--padding) / 2)
var(--color-secondary-dark)
Note: Internally, all variables omit the hawksearch- prefix. This prefix is used only to override the default values.
Breakpoints
This library uses responsive design with the following breakpoints defined:
0px
-sm
740px
-md
990px
-lg
1260px
-xl
1800px
Grid System
This library uses a 12-column, responsive grid system. To use this system, all columns must have a
column
class and be the direct children of an element with arow
class. The number of columns each column elements spans can be controlled withcolumn--XX
classes.For example, the following will render two equal columns that are stacked until the browser window reaches the
Medium
breakpoint:Row Modifiers
The following CSS classes can be added to modify the row display:
row--reverse
row--tight
var(--padding-xs)
Column Modifiers
The following CSS classes can be added to modify the column display:
column--pull-right
Utility Classes
There are several basic utility classes available to quickly customize the display of elements.
Note: All utility classes support the suffixes defined in Breakpoints. For example,
display-block
anddisplay-sm-none
are both valid.Display
Flex Vertical
Flex Gap
var(--padding)
spacing between each child element and allow wrapping onto the next row when necessaryvar(--padding-sm)
var(--padding-xs)
Margin
var(--margin)
var(--margin-sm)
Width
Text Align