react-iztro: rendering a Zi Wei Dou Shu astrolabe as a React component

A component on top of a calculation library

react-iztro is described as a React component based on iztro that generates an astrolabe of Zi Wei Dou Shu, and the distinction between the two pieces is the whole architecture. The iztro library does the work of calculating a chart from birth data, and this project does the work of drawing it. That split is what makes the component small and what makes it usable, since a chart in this tradition is a square divided into twelve palaces with a dense set of symbols in each one, and reproducing that layout is a rendering problem rather than a calculation one. The project is MIT licensed, the primary language is TypeScript, the homepage is docs.iztro.com, and the repository is not archived with the last push on 2026-08-24. The package on npm is react-iztro at version 1.5.0, and the manifest points its main entry at lib/index.js with types at lib/index.d.ts, which tells you the published artefact is a compiled library with declaration files rather than the source.

Installing it takes one command

Installation is the ordinary npm or yarn line for a React component.

npm install react-iztro -S

yarn add react-iztro

The saving here is that the component takes no configuration to get started. The README describes it as a simple, easy to use component with zero configuration and quick integration into your page, and very little learning cost, and the reason is that everything the chart needs comes in as props on a single element. The library also lets you adjust the styling to match your own page, or control whether individual elements are shown or hidden, by overriding the default styles, which is the usual escape hatch for a component that renders a fixed visual layout inside somebody else's design system. The demo of the integrated result is linked in the README, along with a link to an online charting site so you can see what a finished chart looks like before you build anything.

The component API and what the props control

The usage example is short enough to read in one screen, and it shows the shape of the API. You import the Iztrolabe component and render it with a birthday, a birth time, a birthday type, a gender, and optionally a horoscope date and horoscope hour.

import {Iztrolabe} from "react-iztro"

function App() {
  return (
    <div className="App" style={{ width: 1024, margin: '50px auto', boxShadow: '0 0 25px rgba(0,0,0,0.25)'}}>
      <Iztrolabe 
        birthday="2003-10-12" 
        birthTime={1} 
        birthdayType="solar" 
        gender="male" 
      />
    </div>
  );
}

export default App;

So the props map onto the inputs a calculation needs. The birthday is a date string, the birth time is an index rather than a clock time, the birthday type selects the calendar the date is expressed in, and the gender is one of two values. The two horoscope props are the ones the README marks as newer additions, with the horoscope date setting the date used for the limit calculations and defaulting to the current time, and the horoscope hour setting the index of the double-hour used for the hourly limit and defaulting to the time derived from the horoscope date. Everything else about the chart, the palaces, the stars and the limits, is computed rather than passed in, which is what keeps the component's surface so small.

What the chart actually shows

The feature list in the README is really a description of what a chart in this tradition contains, and it is worth reading because it explains why the rendering is not trivial. The complete astrolabe is displayed, including all the major stars, the auxiliary stars, the miscellaneous stars, the four transformations, the special stars and the flowing stars, along with the brightness of each star. Important stars are highlighted, with examples given of the peach blossom star, the release star, the wealth star and the heavenly horse. The layout is the second feature, and the point is legibility. Different colours and font sizes are used to separate the stars, the palace names and the heavenly stems into distinct regions so the chart can be read at a glance, with the stated aim of making the analysis clear and drawing the eye to what matters. The third feature is the limit indicators, which is the part specific to the tradition. The palaces clearly mark where the decade limit, the age limit, the annual, monthly, daily and hourly limits fall, and clicking the limit indicator shows the rearranged limit palace names and the limit four transformations, which the README says makes the stacking palace technique easier to use. The fourth feature is the flowing stars, where the reader chooses which set they are used to working with, since different schools of the tradition favour different ones. The fifth is the triangular and square alignment indicator lines drawn in the centre palace, and the detail here is that the lines follow the smallest selected limit, so if you pick both the annual and the monthly limit the lines point at the monthly one. The sixth is the dynamic limit controls in the centre palace, where the basic information and the alignment lines sit alongside a group of buttons for moving each dimension of the limit. The seventh is the flying star display, where clicking a heavenly stem shows the four transformations it flies out to, coloured by transformation, with red for wealth, blue for power, green for fame and black for obstacle, and a self-transforming stem shown as a coloured bar in front of the star.

Building from source and the storybook workflow

The README documents how to work on the component locally, and the route is fork the repository to your own account, clone it, install the dependencies and start the storybook. The clone and install steps are ordinary.

  git clone https://github.com/SylarLong/react-iztro.git

  npm install

  yarn

The development server is the storybook, and the script is wired to port 6006 rather than the usual default.

   npm run storybook

   yarn storybook

Once it is running you open a browser and go to the local address to preview it. The repository layout confirms that storybook is the development surface, with a .storybook/ directory at the top level alongside the source directory, and the manifest shows the storybook packages in the dev dependencies, with the essentials, interactions, links and onboarding addons, the blocks and react packages, and separate react-vite and react-webpack5 renderers. That pair of renderers is worth noting because it means the components are exercised under both bundlers. The build itself is a TypeScript compile followed by a copy of the CSS files into the output directory, since the styles ship with the package rather than being injected at runtime, and the package manifest ships only the contents of the lib directory.

The scripts tell you what the project checks

The package scripts are a short list and they describe a sensible release process. Linting runs eslint over the TypeScript sources, formatting runs prettier over the same sources, and both are wired into the version lifecycle. The prepublishOnly and preversion hooks run the lint, so a release cannot be made with lint failures. The version hook runs the formatter and stages the source directory, and the postversion hook pushes the commits and the tags, so a version bump is a complete operation rather than a half-finished one. The build is a clean of the output directory followed by the TypeScript compile and the CSS copy. The prepare hook runs the build, which means the library directory is produced automatically when the package is installed from a git URL. There is a separate storybook build target as well as a build-storybook script that does the same thing, which is the kind of small duplication that accumulates in a project over time. The styling of the whole component is CSS files copied into the output, and the ability to override the default styles that the README mentions is delivered through those classes.

Where react-iztro is the wrong choice

The first limit is that it is a React component and nothing else, so a Vue, Svelte or plain web project cannot use it directly, and the calculation library it sits on is the part that would serve those cases. The second is that it is a rendering layer with no abstraction of its own, so everything it shows is decided by iztro, and a chart that a practitioner thinks is missing something cannot be fixed in this repository, only in the library or by overriding the styles, and the override route only covers presentation rather than content. The third is the domain barrier, which is the practical one for a developer outside the tradition. The props encode a calendar system, an hour index convention and a set of limit calculations, and there is no documentation in the README about what the values mean or how the underlying conventions work, so a developer who wants to present charts to users needs that understanding from elsewhere, and the homepage docs site is where it has to come from. The fourth is that the package description and much of the README are in Chinese, which is a practical obstacle for a team that does not read it and a reason the npm metadata carries an English description alongside. The fifth is the version coupling, since the component depends on the library and the two move on their own schedules, so a change in the library's output format can break the rendering in a way that only shows up at runtime, and this repository has no GitHub releases to make matching versions easy.

Editorial conclusion

Adopt react-iztro if you want to show a Zi Wei Dou Shu chart in a React application, since it wraps the iztro calculation library and handles the visual layout so you do not have to. Skip it if you need the chart in a non-React framework, since this is a component and the underlying library is the piece to use elsewhere. Verify first which iztro version your chart depends on, since the component renders whatever the library computes, and that the birth data you pass in matches the type conventions the library expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. SylarLong/react-iztro on GitHub