or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-storybook--addon-centered

A Storybook addon that centers stories in the preview area

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@storybook/addon-centered@5.3.x

To install, run

npx @tessl/cli install tessl/npm-storybook--addon-centered@5.3.0

index.mddocs/

Storybook Addon Centered

A Storybook decorator that centers stories in the preview area using CSS flexbox layout. This addon provides consistent centering behavior across nine different frontend frameworks, making it easy to showcase components with uniform visual presentation regardless of their natural size or positioning.

Package Information

  • Package Name: @storybook/addon-centered
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @storybook/addon-centered --save-dev

Core Imports

ES6 Modules (Framework-specific - Recommended):

import centered from '@storybook/addon-centered/react';
import centered from '@storybook/addon-centered/vue';
import { centered } from '@storybook/addon-centered/angular';
import centered from '@storybook/addon-centered/preact';
import Centered from '@storybook/addon-centered/svelte';
import centered from '@storybook/addon-centered/mithril';
import centered from '@storybook/addon-centered/ember';
import centered from '@storybook/addon-centered/html';
import centered from '@storybook/addon-centered/rax';

Deprecated Main Export (Auto-detects React/Vue):

import centered from '@storybook/addon-centered';

CommonJS (Framework-specific):

const centered = require('@storybook/addon-centered/react');
const centered = require('@storybook/addon-centered/vue');
const { centered } = require('@storybook/addon-centered/angular');
const centered = require('@storybook/addon-centered/preact');
const Centered = require('@storybook/addon-centered/svelte');
const centered = require('@storybook/addon-centered/mithril');
const centered = require('@storybook/addon-centered/ember');
const centered = require('@storybook/addon-centered/html');
const centered = require('@storybook/addon-centered/rax');

Basic Usage

Local Decorator Usage:

import { storiesOf } from '@storybook/react';
import centered from '@storybook/addon-centered/react';

storiesOf('Button', module)
  .addDecorator(centered)
  .add('primary', () => <Button primary>Primary Button</Button>)
  .add('secondary', () => <Button>Secondary Button</Button>);

Global Decorator Usage:

import { configure, addDecorator } from '@storybook/react';
import centered from '@storybook/addon-centered/react';

addDecorator(centered);

configure(() => {
  // Your story loading logic
}, module);

Disabling for Specific Stories:

storiesOf('Button', module)
  .add('uncentered example', () => <Button>Not Centered</Button>, {
    centered: { disable: true }
  });

Architecture

The addon uses Storybook's makeDecorator API to create framework-specific decorators that wrap story components in centered containers. Each framework implementation applies the same CSS flexbox-based centering styles while adapting to the framework's specific rendering patterns:

  • Shared Configuration: Common parameters and styles defined centrally
  • Framework Adapters: Specialized implementations for each supported framework
  • CSS-in-JS Styling: Consistent flexbox layout with framework-appropriate application
  • Parameter System: Integration with Storybook's parameter system for configuration

React Decorator

Provides centering functionality for React components using JSX wrapper elements.

/**
 * React decorator function that centers components in the Storybook preview
 * @param storyFn - Function that returns the React component to be centered
 * @returns JSX element with the component wrapped in centered container divs
 */
function centered(storyFn: () => ReactNode): JSX.Element;

// React types
type ReactNode = React.ReactNode;

interface CenteredStyles {
  style: {
    position: 'fixed';
    top: '0';
    left: '0';
    bottom: '0';
    right: '0';
    display: 'flex';
    alignItems: 'center';
    overflow: 'auto';
  };
  innerStyle: {
    margin: 'auto';
    maxHeight: '100%';
  };
}

Usage:

import { storiesOf } from '@storybook/react';
import centered from '@storybook/addon-centered/react';

storiesOf('MyComponent', module)
  .addDecorator(centered)
  .add('default', () => <MyComponent />);

Vue Decorator

Provides centering functionality for Vue components using template-based wrapping.

/**
 * Vue decorator that creates a wrapper component to center the story
 * @returns Vue component with template and data for centering styles
 */
function centered(): {
  template: string;
  data(): CenteredStyles;
};

interface VueDecoratorConfig {
  template: `
    <div :style="style">
      <div :style="innerStyle">
        <story/>
      </div>
    </div>
  `;
  data(): CenteredStyles;
}

Usage:

import { storiesOf } from '@storybook/vue';
import centered from '@storybook/addon-centered/vue';

storiesOf('MyComponent', module)
  .addDecorator(centered)
  .add('default', () => ({
    components: { MyComponent },
    template: '<my-component />'
  }));

Angular Decorator

Provides centering functionality for Angular components with support for both component and template-based stories.

/**
 * Angular decorator that wraps components with centered styling
 * @param metadataFn - Function returning Angular story metadata
 * @returns Enhanced story metadata with centering template and styles
 */
function centered(metadataFn: StoryFn<IStory>): IStory;

interface IStory {
  component?: any;
  props?: { [key: string]: any };
  moduleMetadata?: NgModuleMetadata;
  template?: string;
  styles?: string[];
}

interface NgModuleMetadata {
  declarations?: any[];
  entryComponents?: any[];
  imports?: any[];
  schemas?: any[];
  providers?: any[];
}

Component Usage:

import { storiesOf } from '@storybook/angular';
import { centered } from '@storybook/addon-centered/angular';
import { AppComponent } from './app.component';

storiesOf('App', module)
  .addDecorator(centered)
  .add('default', () => ({
    component: AppComponent,
    props: { title: 'My App' }
  }));

Template Usage:

storiesOf('Button', module)
  .addDecorator(centered)
  .add('with template', () => ({
    template: '<button>Click me</button>',
    moduleMetadata: {
      declarations: [ButtonComponent]
    }
  }));

Preact Decorator

Provides centering functionality for Preact components using h() function and JSX.

/**
 * Preact decorator that centers components using Preact's h function
 * @param storyFn - Function that returns the Preact component to center
 * @returns Preact VNode with centered wrapper elements
 */
function centered(storyFn: () => Component): JSX.Element;

// Preact types  
type Component = preact.Component;

Usage:

import { storiesOf } from '@storybook/preact';
import centered from '@storybook/addon-centered/preact';

storiesOf('MyComponent', module)
  .addDecorator(centered)
  .add('default', () => <MyComponent />);

Svelte Decorator

Provides centering functionality for Svelte components using a wrapper component approach.

/**
 * Svelte decorator that wraps components with a centering Svelte component
 * @param storyFn - Function returning Svelte component configuration
 * @returns Enhanced component configuration with centering wrapper
 */
function centered(storyFn: () => SvelteStoryConfig): SvelteStoryConfig;

interface SvelteStoryConfig {
  Component: any;
  props?: { [key: string]: any };
  on?: { [key: string]: Function };
  Wrapper?: any;
  WrapperData?: {
    style: string;
    innerStyle: string;
  };
}

Usage:

import { storiesOf } from '@storybook/svelte';
import Centered from '@storybook/addon-centered/svelte';
import Component from './Component.svelte';

storiesOf('Component', module)
  .addDecorator(Centered)
  .add('default', () => ({
    Component,
    props: { text: 'Hello World' }
  }));

Mithril Decorator

Provides centering functionality for Mithril components using the framework's view function pattern.

/**
 * Mithril decorator that creates a view function wrapper for centering
 * @param storyFn - Function returning Mithril component types
 * @returns Mithril component with view function that renders centered content
 */
function centered(storyFn: () => ComponentTypes): {
  view(): m.Vnode;
};

// Mithril types
type ComponentTypes = m.ComponentTypes;

Usage:

import { storiesOf } from '@storybook/mithril';
import centered from '@storybook/addon-centered/mithril';

storiesOf('MyComponent', module)
  .addDecorator(centered)
  .add('default', () => ({
    view: () => m(MyComponent, { text: 'Hello' })
  }));

Ember Decorator

Provides centering functionality for Ember components using DOM manipulation and appendTo pattern.

/**
 * Ember decorator that manipulates DOM elements to center story content
 * @param storyFn - Function returning Ember story configuration
 * @returns Story configuration with modified DOM element for centering
 */
function centered(storyFn: () => EmberStoryConfig): EmberStoryConfig;

interface EmberStoryConfig {
  template: any;
  context: any;
  element?: HTMLElement;
}

Usage:

import { storiesOf } from '@storybook/ember';
import centered from '@storybook/addon-centered/ember';

storiesOf('MyComponent', module)
  .addDecorator(centered)
  .add('default', () => ({
    template: hbs`{{my-component}}`,
    context: {}
  }));

HTML Decorator

Provides centering functionality for HTML strings and DOM nodes with automatic type detection.

/**
 * HTML decorator that handles both string HTML and DOM nodes for centering
 * @param storyFn - Function returning HTML string or DOM node
 * @returns Centered wrapper element containing the story content
 */
function centered(storyFn: () => string | Node): HTMLDivElement | any;

Usage:

import { storiesOf } from '@storybook/html';
import centered from '@storybook/addon-centered/html';

storiesOf('HTML', module)
  .addDecorator(centered)
  .add('string', () => '<button>Click me</button>')
  .add('dom node', () => {
    const button = document.createElement('button');
    button.textContent = 'Dynamic Button';
    return button;
  });

Rax Decorator

Provides centering functionality for Rax components using Rax View components and JSX.

/**
 * Rax decorator that wraps components with Rax View components for centering
 * @param storyFn - Function returning Rax components
 * @returns Rax View elements with centered layout
 */
function centered(storyFn: () => any): JSX.Element;

Usage:

import { storiesOf } from '@storybook/rax';
import centered from '@storybook/addon-centered/rax';

storiesOf('MyComponent', module)
  .addDecorator(centered)
  .add('default', () => <MyComponent />);

Configuration and Parameters

All decorators support the same parameter configuration for consistent behavior across frameworks.

interface CenteredParameters {
  /**
   * Configuration options for the centered addon
   */
  centered?: {
    /**
     * Disable centering for this specific story
     * @default false
     */
    disable?: boolean;
  };
}

Disabling Centering:

// Disable centering for a specific story
.add('uncentered', () => <Component />, {
  centered: { disable: true }
});

Styling Details

The addon uses consistent CSS-in-JS styling across all frameworks:

interface CenteredStyles {
  /**
   * Outer wrapper styles for full-viewport positioning and flexbox layout
   */
  style: {
    position: 'fixed';
    top: '0';
    left: '0';
    bottom: '0';
    right: '0';
    display: 'flex';
    alignItems: 'center';
    overflow: 'auto';
  };
  
  /**
   * Inner container styles for centering content with IE11 compatibility
   */
  innerStyle: {
    margin: 'auto';
    maxHeight: '100%';
  };
}

The centering approach uses CSS flexbox with alignItems: 'center' for vertical centering and margin: 'auto' for horizontal centering, ensuring compatibility across different browsers and frameworks while maintaining consistent visual presentation.

Deprecated Main Export

The main export provides automatic framework detection but is deprecated in favor of explicit framework imports.

/**
 * @deprecated Use framework-specific imports instead
 * Main export that auto-detects between React and Vue based on STORYBOOK_ENV
 * @returns React centered decorator for React environments, Vue for Vue environments
 */
declare const Centered: () => any;
export default Centered;

Usage (Deprecated):

import centered from '@storybook/addon-centered';

// Automatically uses React decorator in React Storybook
// or Vue decorator in Vue Storybook
storiesOf('MyComponent', module)
  .addDecorator(centered)
  .add('default', () => <MyComponent />);

Helper Functions

JSON to CSS Converter

Utility function for converting CSS-in-JS objects to CSS strings, used internally by framework implementations.

/**
 * Converts CSS-in-JS style objects to CSS string format
 * @param jsonStyles - Object with CSS properties as keys and values
 * @returns CSS string representation of the styles
 */
function json2CSS(jsonStyles: Partial<CSSStyleDeclaration>): string | null;

Usage:

import json2CSS from '@storybook/addon-centered/dist/helpers/json2CSS';

const styles = {
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center'
};

const cssString = json2CSS(styles);
// Returns: "display: flex; align-items: center; justify-content: center;"