Skip to main content

Getting Started

hass-react is a headless React library that provides hooks and components for building Home Assistant user interfaces without the hassle of WebSockets or service calls.

Installation​

npm install hass-react

Setup​

Wrap your app with HAProvider and point it to your Home Assistant instance:

import { HAProvider } from 'hass-react'

function App() {
  return (
    <HAProvider url="http://homeassistant.local:8123">
      <YourApp />
    </HAProvider>
  )
}

The provider handles authentication automatically using OAuth 2.0 (recommended) or long-lived tokens.

Your First Control​

hass-react offers two ways to work with entities: components with render props or hooks for direct access.

Using Components (Render Props)​

import { Light } from 'hass-react'

function LightControl() {
  return (
    <Light entityId="light.floor_lamp">
      {({ isOn, toggle, attributes }) => (
        <div>
          <h3>{attributes.friendly_name}</h3>
          <button onClick={toggle}>
            {isOn ? 'Turn Off' : 'Turn On'}
          </button>
        </div>
      )}
    </Light>
  )
}

Using Hooks​

import { useLight } from 'hass-react'

function LightControl() {
  const light = useLight('light.floor_lamp')
  
  return (
    <div>
      <h3>{light.attributes.friendly_name}</h3>
      <button onClick={light.toggle}>
        {light.isOn ? 'Turn Off' : 'Turn On'}
      </button>
    </div>
  )
}

Both approaches give you the same functionality - choose the pattern you prefer!

Performance Benefits​

hass-react is built for efficiency:

  • Shared subscriptions - Multiple components watching the same entity automatically share a single WebSocket subscription
  • Automatic cleanup - Subscriptions are removed when components unmount, preventing memory leaks
  • Lazy loading - Only entities that are actually rendered are subscribed to

This means you can build complex dashboards with dozens of entity displays without worrying about performance or connection overhead.

Next Steps​