Utilities
Reusable functions for improved workflow
Source ↗️ Report Issue ↗️Some components in Webcore comes with JavaScript API that let’s you dynamically handle components. Apart from this functionality, Webcore also exposes a couple of other utility functions that you can use in your own codebase to speed up your development workflow. You’ll find the following utility function in Webcore.
webcoreui
. If you’d like to reuse some of the functionalities defined here in your own project without Webcore, you can find the implementations here. ClassNames
Use the classNames
function to dynamically and conditionally generate valid CSS class names. The function expects an array of elements. You can create conditions inside the array using logical operators. The array elements will be concatenated into a single class name.
Cookies
To work with cookies, use the getCookie
, setCookie
, and removeCookie
functions.
-
Getting cookies
Expects the name of the cookie as a string, and returns the value of the cookie if present. Returns
null
if no cookie is found. -
Setting cookies
Sets the cookie for a specified duration. Expects, the name of the cookie as a string, the value of the cookie as a string, and the number of days in numbers. In the above example, the
w-theme
cookie will be set for 30 days before expiration with the value oftheme-dark
. -
Removing cookies
Removes the specified cookied. Pass the name of the cookie as a string you’d like to remove. No value is returned from the function.
Debounce
Use the debounce
function to limit the rate at which a function is executed. Use for performance optimization for excessively executed functions, such as keyup, resize, or scroll events:
Pass the callback function to the debounce
call that should be rate limited. Optionally, you can set a second parameter to configure the timeout for the debounce. By default, this is set to 100 milliseconds.
DOM Utilities
Webcore provides the following DOM utility functions to make the work with DOM elements easier in Astro components:
-
Getting DOM elements
Use the
get
utility function to select DOM elements. Passtrue
as the second parameter to get all DOM elements with the specified selector. The selector can be a valid HTML query selector. -
Adding event listeners
To add event listeners in your Astro components, you can use the above utility function. It expects the following parameters:
selector
: Pass a query selector as the first parameter where you want to attach the event listener. This can also be a variable that references an HTML element.event
: Pass the event for the event listener.callback
: Pass the callback function that should be executed once the event is triggered.
You can also use the
on
utility function to attach events listeners to multiple elements by setting the fourth parameter totrue
:This will query all elements with the
.my-buttons
selector, and add a click event listener to each one of them.
Events
To work with custom events, use the dispatch
and listen
functions:
listen
: Thelisten
function expects the name of the event as a string for the first parameter, and a callback function as the second parameter. The callback function has access to the payload sent by thedispatch
in the second parameter.dispatch
: To send the event, calldispatch
with the name of the event of your choice. In the second parameter, you can send a payload along with the event. Anylisten
call subscribed to the event will receive the payload when the event is triggered by thedispatch
call.
If you need to remove the listener later on, you can assign the listen
function to a variable, and call the remove
method:
Use the two utility functions in combination to share data between different parts of your application that are otherwise unrelated. This approach is known as the publish-subscribe design pattern, or pub/sub for short.
Interpolate
You can use the following math functions if you need to transform numbers in various ways:
clamp
: Restrict a value to lie within a specified range.lerp
: Find a value that is a given fraction between a start and end value.invlerp
: Find the fraction at which a given value lies between a start and end value.interpolate
: A combination oflerp
andinvlerp
to map values from one range to another.
-
Clamp
Use cases:
- User Input Validation: Ensuring that user inputs stay within a valid range, such as volume levels (0 to 100).
- Animation Control: Limiting the position or size of elements within the bounds of a container.
-
Lerp
Use cases:
- Smooth Animations: Gradually moving an element from one position to another or transitioning between colors.
- Blending Values: Combining two values based on a weight.
-
Inverse Lerp
Use cases:
- Mapping Values: Mapping a value from one range to another, which is useful in normalization or data scaling.
- Progress Indicators: Determining the progress percentage of a task or loading bar based on the current value.
-
Interpolate
Use the
interpolate
function if you need to provide both the input and output ranges.
Modals & Sheets
To open modals or sheets, you’ll need to create a Modal
/Sheet
component first:
Based on the above selectors, you can target this component to trigger it using the modal
function:
You can open modals in two different ways:
- Open: Pass a configuration object with a
trigger
property that specifies a query selector for a trigger element, and pass amodal
property to target theModal
/Sheet
component. Clicking on the trigger element will now open the component. - Open via JS: Pass a query selector to the
modal
function that targets the component, and assign the function to a variable. You can call theopen
method on the assigned variable. This lets you trigger the component programmatically, for example, after a network request finishes.
The JavaScript API of the Modal
and Sheet
components are identical. To learn more about how to use the Modal
component, visit its documentation. To learn more about how to use the Sheet
component, you can find its documentation here.
Popovers
To create popovers, you’ll need to create a Popover
component first:
As popovers are attached to interactive elements, you’ll also need to create an interactive element, such as a button, that can trigger the popover. In this example, a Button
component is used.
Based on the above selectors, you can target this popover to initialize it:
Whenever the .trigger-popover
button is clicked, it’ll open the .my-popover
element. The popover
function also returns a remove
function that can be used to remove the created popover instance.
To learn more about how to use the Popover
component, visit its documentation.
Toasts
To dynamically show toasts, you’ll need to create a Toast
component first:
Based on a selector, you can target this toast to trigger it:
To configure the behavior of your toast, pass a configuration object to the toast
function:
To learn more about how to use the Toast
component, visit its documentation.
Request improvement for this page