How to build a Circular Navigation with react-planet — Setup, Examples & Customization
A focused, practical guide to using react-planet to make radial / orbital navigation in React apps. We cover installation, a live-ready example, customization of animations and styles, accessibility concerns, and integration tips.
What is react-planet and when to use it
react-planet is a small React component pattern (available as a package in common ecosystems) that arranges child items in a circular, orbital layout around a center element. Think of a floating center "planet" with satellites — each satellite is a menu item. It's a visual pattern useful for compact tool menus, creative navigation, or action pickers where space and motion add clarity.
Use react-planet when you want to give a distinct, visual affordance to grouped actions — for example, editing controls, media actions in a card, or a contextual floating menu. It's not a replacement for global navigation, but it shines as a contextual, interactive UI element.
Keep in mind: circular menus are eye-catching, but must remain usable. Implement sensible hit areas, keyboard access, and responsive fallbacks. We'll cover these later under accessibility and best practices.
Installation & getting started
To get started, install the package (assuming it's published to npm). Use either npm or yarn — both are supported in most projects. The typical install command is:
npm install react-planet
# or
yarn add react-planetThen import the component into your React app and render it with children representing menu items. The simplest working example uses minimal props and demonstrates the orbital layout right away.
If you prefer a guided tutorial before coding, check this react-planet tutorial which walks through concepts and demos.
Basic example: minimal implementation
Below is a typical minimal usage pattern. The API names may vary slightly depending on the version; treat props as examples you can adapt. This example positions three items around a center button.
import React from 'react';
import { Planet } from 'react-planet';
export default function PlanetMenu(){
return (
<Planet
centerContent=<button>Menu</button>
startAngle={-90}
radius={80}
open={true}
>
<button onClick={()=>alert('A')}>A</button>
<button onClick={()=>alert('B')}>B</button>
<button onClick={()=>alert('C')}>C</button>
</Planet>
)
}This component arranges children around the center, controlled by props like start angle, radius, and open state. You can toggle open/close with state and animate the changes (see the animations section).
For sandboxing and iterative tweaking, copy the example to CodeSandbox or StackBlitz and manipulate radius/startAngle to see how layout changes. Live tweaking often yields better UX than guesswork.
Customization: styles, props and animations
Customization is where react-planet gets interesting. Typical props let you change radius, start angle, animation durations, easing, and the center element. You can also style individual children with CSS or inline styles for colors, sizes, and shadows.
Animations are usually CSS-driven (transforms + transitions) or handled via inline styles updated through state. For smoother motion, prefer transform: translate/rotate + opacity instead of switching top/left. GPU-accelerated transforms prevent janky motion on mobile devices.
Example: apply a staggered entrance by calculating a per-item transition delay based on index. Combine with easing functions to achieve orbital easing. Keep animation durations short (200–400ms) for menus to remain snappy.
Accessibility & mobile considerations
Circular menus must be accessible. Provide keyboard focusability: set tabIndex on buttons, ensure the center toggle is reachable, and implement arrow-key navigation if logical for your use case. Use ARIA attributes to indicate expanded/collapsed state (aria-expanded) and role attributes for menu semantics (role="menu"/"menuitem" where appropriate).
On small screens, the orbital layout can become cramped or create overlapping hit areas. Use a responsive fallback — switch to a vertical menu or a modal sheet on narrow viewports. Detect viewport width or measure available space, then flip layout responsively.
Performance tip: avoid rendering heavy components as children of each menu item unless needed. Render lightweight elements and lazy-load heavy content upon activation to keep animations smooth.
Integration patterns: React Router and dynamic items
Integrating with client-side routing is straightforward: use Link components as children if you want navigation without full reloads. Just make sure Link is focusable and styled similarly to regular buttons.
For dynamic menus (data-driven items), map an array of action descriptors to children. Keep unique keys and avoid recreating functions inline on every render to prevent unnecessary reflow/animation restarts.
When updating the items list, consider animating enter/exit with libraries like react-transition-group or CSS transitions tied to a 'visible' class. Smooth transitions prevent jarring layout jumps.
Troubleshooting & best practices
If items overlap or positions look wrong, verify your center position and radius match the layout box size. Use developer overlays (borders/background colors) temporarily to debug bounding boxes. Many common issues come from parent components with transform/position styles affecting child coordinate space.
Avoid animating layout properties like top/left — prefer transform translate/rotate. If you see jank on mobile, lower animation durations or disable animations for reduced-motion users via prefers-reduced-motion media query.
Document the props you use in your internal design system and provide sensible defaults. Consumers appreciate an 'unstyled' mode for library components so they can apply consistent design tokens.
References & resources
Official React docs are useful when you need to revisit event handling and performance patterns: React docs. For a practical tutorial and a demo-driven walkthrough, see this react-planet tutorial.
To install, check the package page on npm (use anchor text matching install intent): react-planet installation. If you prefer repo sources and issues, search the component's GitHub repository for the authoritative README and examples.
Finally, for patterns and alternatives, look for 'radial menu' or 'floating action menu' implementations if you need different ergonomics or licensing.
- react-planet tutorial (tutorial & walkthrough)
- react-planet installation (npm package)
- React docs