iztro-hook
iztro-hook wraps iztro’s chart and horoscope calculations in a React Hook. Use useIztro to get the data and render your own chart, table, or filter controls. For a ready-made interactive chart, use react-iztro. Outside React, you can use iztro directly.
Installation
npm install iztro iztro-hookThe examples and parameters below are based on iztro-hook 1.3.5 and iztro 2.6.5.
Get chart and horoscope data
Call useIztro at the top level of a React function component or custom Hook. On the first render, both astrolabe and horoscope may be undefined. Check that the data is available before rendering the results.
import React from 'react';
import { useIztro } from 'iztro-hook';
export default function App() {
const { astrolabe, horoscope, setHoroscope } = useIztro({
birthday: '2000-8-16',
birthdayType: 'solar',
birthTime: 2,
gender: 'female',
lang: 'en-US',
});
if (!astrolabe || !horoscope) {
return <p>Generating chart…</p>;
}
return (
<section>
<p>Lunar birth date: {astrolabe.lunarDate}</p>
<p>Horoscope date: {horoscope.solarDate}</p>
<p>Yearly heavenly stem and earthly branch: {horoscope.yearly.heavenlyStem}{horoscope.yearly.earthlyBranch}</p>
<button type="button" onClick={() => setHoroscope('2025-10-19', 2)}>
View horoscope for October 19, 2025, at 03:00–05:00 (yin hour)
</button>
</section>
);
}Scroll here to load the runnable example.
Chart inputs
| Parameter | Type | Description |
|---|---|---|
birthday | string | Required. Birth date, such as '2000-8-16'. birthdayType determines whether the date is Gregorian or lunar. |
birthdayType | 'solar' | 'lunar' | Required. Use 'solar' for a Gregorian date or 'lunar' for a lunar date. |
birthTime | number | Required. Birth double-hour index, from 0 to 12. For example, 2 is the yin hour(寅時) and 12 is the late Zi hour(晚子時). |
gender | GenderName | Required. For English, use 'male' or 'female'. |
isLeapMonth | boolean | Whether the lunar birth date falls in a leap month. Defaults to false. |
fixLeap | boolean | Whether to apply the leap-month adjustment when generating the chart. Defaults to true. See astro.withOptions(). |
lang | Language | Output language for chart and horoscope data. An explicit value takes precedence over options.language. |
astroType | AstroType | Chart type. 'heaven' is the default natal chart(天盤), 'earth' selects the earth chart(地盤), and 'human' selects the human chart(人盤). |
options | Config | Configuration for the current chart. For example, { yearDivide: 'exact' } uses the Beginning of Spring(立春) as the year boundary. |
If the birth details come from a form, validate them before rendering the child component that calls the Hook. A blank or unparseable date skips chart calculation, so previous results may still be displayed. Other invalid inputs can cause iztro to throw an error. See chart configuration and input validation.
Return values
| Field | Description |
|---|---|
astrolabe | A FunctionalAstrolabe instance. Read data such as the twelve palaces(十二宮) and major stars(主星), or call its methods to make additional queries. |
horoscope | A FunctionalHoroscope object containing decadal(大限), age-based(小限), yearly(流年), monthly(流月), daily(流日), and hourly(流時) results. The initial calculation uses the current local date and double-hour. |
setHoroscope(date, hour?) | Updates the horoscope query. date accepts a Gregorian date string or a Date. hour accepts a double-hour index from 0 to 12. When you omit hour, the Hook converts the local hour of the supplied date to a double-hour index. |
setHoroscope returns void. Read the updated horoscope on a subsequent render. The call updates the horoscope query, while the Hook inputs still determine the birth details.