Skip to content


Development scheme based on Web Components


  1. High Cross-Framework Compatibility: Our solution seamlessly adapts to a wide array of leading front-end frameworks, including React, Vue, Preact, SolidJS, Svelte, and more. It also integrates smoothly with any project built on JavaScript and adhering to W3C standards. No matter your choice of technology stack, we guarantee consistent and reliable support.
  2. Pure Native Experience: Our solution eliminates the need for dependencies on front-end frameworks like npm, React/Vue, or complex build tools such as webpack/vite. It truly embodies the essence of Web technology. You can get started effortlessly, just like manipulating native div tags, immediately experiencing the purity and intuitiveness of the technology. This design not only simplifies project structure but also reduces the cost of learning and usage, enabling every developer to appreciate the native charm of Web technology.
  3. Ultimate Modular Design: Utilizing the principle of minimal modularization, we carefully dismantle large and complex systems or applications into extremely small, functionally independent, and easily reusable component units. This approach significantly enhances code maintainability, scalability, and reusability.
  4. Fully Open-Source for Free Learning: Our project fully adheres to the MIT open-source license, granting unrestricted access to all source code. This means you are free to access, learn from, reference, and even modify our code, whether for personal development or commercial applications. We firmly believe that open-source is a vital pathway for technological advancement and innovation.
  5. Interactive and Comprehensive Documentation: We provide detailed and highly interactive documentation, where all component examples are live and interactive. This allows you to directly experience the component functionality while reading, deepening your understanding and enabling quick hands-on learning. This design is aimed at providing you with the most intuitive and efficient learning experience possible.
  6. Type-Checking Support: Our development environment is fully built on TypeScript, equipped with comprehensive declaration files and type definitions, ensuring smooth integration for both JavaScript and TypeScript projects. With powerful type-checking capabilities, we significantly enhance code readability, maintainability, and project robustness, bringing unprecedented convenience and peace of mind to development work.
  7. Enhanced Durability and Stability: Our solution offers exceptional stability, eliminating concerns about disruptive updates encountered during version upgrades, such as React from version 15 to 16 (with fiber) or Vue from version 2 to 3 (with hooks). We ensure that your components won't be forced into unnecessary updates or redevelopments, thus avoiding potential project interruptions and additional workloads. This translates into a continuous and hassle-free project operation.


Build Statusnpm-vnpm-dbrotlimodule formats: umd, esm


In most cases, you can use it just like a native div tag.

Here are some examples

  1. html
  2. js
  3. jsx
  4. vue
  5. tsx


<script src="./ranui/dist/umd/index.umd.cjs"></script>



import 'ranui';

const Button = document.createElement('r-button');
Button.appendChild('this is button text');


Because react synthetic events, in order to more convenient to use, by react higher-order components encapsulation ranui, Output the @ranui/react

In react, use the @ranui/react will be more smooth, by higher-order functions after package, and react ecosystem.

ranui, however, still can be in any js or ts in use.

import 'ranui';
const App = () => {
  return (


import 'ranui';


Because react synthetic events, in order to more convenient to use, by react higher-order components encapsulation ranui, Output the @ranui/react

In react, use the @ranui/react will be more smooth, by higher-order functions after package, and react ecosystem.

ranui, however, still can be in any js or ts in use.

// react 18
import type { SyntheticEvent } from 'react';
import React, { useRef } from 'react';
import 'ranui';

const FilePreview = () => {
  const ref = useRef<HTMLDivElement | null>(null);
  const uploadFile = (e: SyntheticEvent<HTMLDivElement>) => {
    if (ref.current) {
      const uploadFile = document.createElement('input');
      uploadFile.setAttribute('type', 'file');;
      uploadFile.onchange = (e) => {
        const { files = [] } = uploadFile;
        if (files && files?.length > 0 && ref.current) {
          ref.current.setAttribute('src', '');
          const file = files[0];
          const url = URL.createObjectURL(file);
          ref.current.setAttribute('src', url);
  return (
      <r-preview ref={ref}></r-preview>
      <r-button type="primary" onClick={uploadFile}>
        choose file to preview

jsx defines the types of all HTML-native components in TypeScript. The type 'web component' is not in the jsx definition. You need to add it manually. Otherwise there is a type problem, but it actually works.

// typings.d.ts
interface RButton {
  type?: string;
  onClick?: React.MouseEventHandler<HTMLDivElement> | undefined;

interface RPreview {
  src?: string | Blob | ArrayBuffer;
  onClick?: React.MouseEventHandler<HTMLDivElement> | undefined;
  ref?: React.MutableRefObject<HTMLDivElement | null>;

declare namespace JSX {
  interface IntrinsicElements {
    'r-preview': React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> & RPreview;
    'r-button': React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> & RButton;


Support for on-demand import

import 'ranui/button';

For some globally displayed components, such as preview and message, additional styles need to be loaded

import 'ranui/preview';
import 'ranui/style';

It can also be imported globally, which is more convenient, so that there is no need to consider anything, so that it is done.

  • ES module
import 'ranui';
<script src="./ranui/dist/umd/index.umd.cjs"></script>


  • Button
Primary button
Warning button
Text button
Default button
  • Icon
  • Skeleton
  • Input
  • message
Information promptWarning promptError promptSuccess tiptoast tip
  • Tab
  • Radar
  • Progress
  • Player
  • Select


  • react

@ranui/react By react higher-order functions encapsulated ranui and become, Event events follow react Event specification. It is slightly different from the W3C standard.

  • Modern 'web' standards

In the W3C standard, you can use the on attribute to define event handlers on HTML elements. But this is the old event handler approach.

Modern web development recommends the addEventListener method.

<r-button id="button">Button</r-button>

  const button = document.getElementById('button');
  button.addEventListener('click', function (event) {
    alert('New click event!');

However, if you do need to use the 'on' attribute, here is an example:

<r-input onchange="change(this.value)"></r-input>

  function change(e) {
    console.log('e--->', e);

Note that using the 'on' attribute to define event handlers has some limitations and disadvantages.

For example, you can't use event capture or event delegation, and each event type requires a separate attribute.

This is why the addEventListener method is recommended for modern web development.

You can also use the 'property' method:

<r-input id="input"></r-input>

  const input = document.getElementById("input")
  input.onchange = (e) {
    console.log('e--->', e)



<r-input id="input"></r-input>

  /* #input refers to the current custom element
input in ::part(input) refers to the class  of the Shadow DOM element inside the current custom element*/
  #input::part(input) {
    width: 100px;

For specific pseudo-class names(::part), please refer to the specific introduction.

Pass in by attribute

A sheet attribute is added to all components, passing in a CSSStyleSheet string. It will be inserted directly into the Shadow DOM.

CSS3 variable var

By setting the CSS3 variable for a component, you can customize the specified styles within the component, such as:

<r-progress percent="0.7" type="drag"></r-progress>
  style="--ran-progress-wrap:linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);"

For specific CSS3 variable names, refer to the introduction and description of each component.


  • Do not support IE, others have better support



  1. 优秀的组件设计
  2. 在线生成 CSS 渐变色
  3. 优秀设计作品,有 psd 和 sketch
  4. 3D UI 设计,类似于 3D 版的 figma
  5. 设计规范
  6. 优秀设计作品
  7. element UI 中文网
  8. Ant design 中文网
  9. 在线绘制 CSS 动画
  10. tailwindcss
  11. animate css
  12. can i use
  13. figma

Protocols and standards

  1. RFCs
  2. ECMA
  3. w3c

Released under the MIT License.