Liquid Oxygen comes with React bindings for all Web Components. Although the rendered components are still Web Components, the bindings improve the developer experience by providing a more familiar API and a better integration with React.
On this page, you'll find detailed instructions on how to integrate Liquid Oxygen into your React project and how to use the components.
Liquid Oxygen is easy to integrate into an existing React project. We assume you already have a project set up. If not, you can create a new project with Vite.
npm create vite@latest your-project-name -- --template react-ts
For more information about this command and Vite, please refer to the Vite documentation.
Although this guide assumes your project is using typescript, all examples should also be applicable to javascript projects.
Add Liquid Oxygen to your project with the package manager of your choice.
npm install @emdgroup-liquid/liquid
npm
, yarn
or pnpm
). For simplicity, we use npm
in this guide.
All Web Components are loaded togehter with their styles embedded. Therefore we only need to import the global stylesheet for Liquid Oxygen.
Add the following code to your App.tsx
file (or any similar file which is loaded for every page).
// App.tsx
import '@emdgroup-liquid/liquid/dist/css/liquid.global.css'
When adding Liquid Oxygen components to a React project, it is crucial to use the React bindings. All components are imported from @emdgroup-liquid/liquid/dist/react
. The bindings significantly improve JSX compatibility and your developer experience.
Let's have a look at how to add a LdButton to your project. This examnple also includes a LdIcon as it helps you to check if Liquid Oxygen assets are loaded correctly.
// SampleComponent.tsx
import { LdButton, LdIcon } from '@emdgroup-liquid/liquid/dist/react'
export function SampleComponent() {
return (
<LdButton>
Click me!
<LdIcon name="energy" />
</LdButton>
)
}
When you put this component on a page, you should see a blue button with the text "Click me!" and a lightning bolt icon.
Liquid Oxygen components aim to work similarly to native HTML elements as much as possible. In most cases, you can expect the same events and behavior from a Liquid Oxygen component and its native equivalent. Custom events are documented on the respective component pages.
Let's take our button from above and add a click handler.
// SampleComponent.tsx
import { LdButton, LdIcon } from '@emdgroup-liquid/liquid/dist/react'
export function SampleComponent() {
return (
<LdButton onClick={() => alert('Clicked!')}>
Click me!
<LdIcon name="energy" />
</LdButton>
)
}
Please notice the camel case notation of the onClick
prop. This is the expected React convention but differs from the native onclick
attribute and documentation. As we do not explicitly document these events, you need to apply this convention yourself. Typescript and your code editor's IntelliSense will assist you with that.
There are a few cases where native events of Web Components do not behave as expected by React. In these cases, Liquid Oxygen provides custom events prefixed with ld
and documented on the respective component pages.
onChange
event invokes when the component loses focus (and the value changed). This is the standard browser behavior but differs from the native React onChange
event. Use the onInput
event in cases you want to handle user input immediately while typing. Find additional information in the Event handling guide.
This guide shows you how to get started with Liquid Oxygen in your React project. Additionally, we provide several sandbox applications showing how to use Liquid Oxygen in various environments:
If you still struggle integrating Liquid Oxygen, feel free to get in touch with us.