BorderBeam

Decorative component that renders a moving beam along a container border.

When To Use

• Use when a container needs stronger visual emphasis without introducing business state semantics.
• Suitable for login panels, recommendation cards, AI modules, and key CTA blocks.
• As a decorative effect, it should not replace focus rings, validation borders, or status feedback.

Examples

• Basic · basic
• Show on hover · hover
• Multiple beams · count
• Custom container · custom-container
• Gradients · customized-color
• Duration · duration
• Size · size
• Line width · line-width

API

Common props ref：Common props

BorderBeam

Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

Native ComponentToken declares no directly extractable own fields. Shared tokens and inheritance are defined by the declarations below.

Declaration source: vendor/components/border-beam/style/index.ts

import type { CSSObject } from '@ant-design/cssinjs';

import { Keyframes, unit } from '@ant-design/cssinjs';

import { genNoMotionRawStyle } from '../../style/motion';

import type { FullToken, GenerateStyle } from '../../theme/internal';

import { genStyleHooks } from '../../theme/internal';

import { genCssVar } from '../../theme/util/genStyleUtils';

import { DEFAULT_BORDER_BEAM_DURATION, MAX_BEAM_COLOR_STOP_PERCENT } from '../util';

export type ComponentToken = object;

interface BorderBeamToken extends FullToken<'BorderBeam'> {}

FAQ

How does BorderBeam behave when reduced motion is enabled?

BorderBeam treats the beam as a decorative effect. When prefers-reduced-motion: reduce is active, the beam effect is hidden.

What does percent mean in color?

percent represents the authored stop position and accepts values from 0 to 100. BorderBeam maps those stops into the visible beam segment and reserves the trailing area for transparent fade-out so the moving tail stays visible.

size limits

BorderBeam creates the beam with a square gradient layer whose side length is size. The layer travels around the container border, and a mask exposes the areas where it overlaps the border. size sets the side length independently of the border path length.

Along a horizontal edge, the gradient layer extends about size / 2 to either side of the edge. If size approaches or exceeds twice the mask overlay height, the square can cover both the top and bottom edges. The same geometry applies to the width while the beam travels along a vertical edge.

Keep size well below twice the shorter side of the mask overlay: size < 2 × min(width, height). The mask overlay is usually close in size to the decorated container, while outset changes its dimensions. Border radius, lineWidth, and transparent areas in the gradient also affect the point at which the overlap becomes visible.

Why is BorderBeam not working?

BorderBeam needs to resolve the actual DOM node from children and insert the beam layer into that node. Make sure the wrapped content is a native DOM element, or a React component that correctly forwards its ref to a DOM element. Otherwise BorderBeam cannot locate the real container and the beam cannot be rendered.

The beam layer is positioned with position: absolute, so the resolved DOM node also needs to provide a positioning context. In most cases, set position: relative on the wrapped element. BorderBeam does not inspect or patch the child positioning style for you.

For performance reasons, whether children can host the beam and its positioning information are resolved during initialization, and are not continuously updated when the child structure or positioning styles change later.

How do I keep the beam radius aligned with my container?

BorderBeam renders the beam layer as a child of the actual container and directly inherits its radius through border-radius: inherit. For a single-container child such as Card, the beam automatically follows the container radius. For more complex child trees, make sure the radius is set on the actual container root.

The radius stays in sync through CSS inheritance, without being read or measured during initialization. Later changes made through className, responsive styles, or CSS variables are automatically reflected by the beam layer.

Shared native props

Tips: The following generic properties apply to most antd components; those not supported are described separately.

Install and reproduce an example

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

• vendor/components/border-beam/BorderBeam.tsx
• vendor/components/border-beam/BorderBeamEffect.tsx
• vendor/components/border-beam/style/index.ts
• vendor/components/border-beam/util.ts

Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.