## Feature Examples

### Size
- description: Control button size with `size` prop: - `large` is best for calls to action that require more emphasis. - `medium` is for main page actions and common use cases. - `small` fits into smaller UI elements like cards and widgets. - `tiny` is used for dense layouts.
- example:
```jsx
<StorybookComponents.Stack>
  <Button size="large">Large</Button>
  <Button size="medium">Medium</Button>
  <Button size="small">Small</Button>
  <Button size="tiny">Tiny</Button>
</StorybookComponents.Stack>;
```

### Priority
- description: Each button has a `priority` that signals its importance. Use it to create a clear visual hierarchy across actions on the page. - `primary` is the main call-to-action. - `secondary` is for supporting actions alongside a primary (e.g. Cancel, Back). - `tertiary` is for low-emphasis actions; use when secondary would still feel too prominent. _Note_: There should only be one primary button per page.
- example:
```jsx
() => (
  <Box gap="12px" verticalAlign="middle">
    <Button>Primary</Button>
    <Button priority="secondary">Secondary</Button>
    <Button priority="tertiary">Tertiary</Button>
  </Box>
);
```

### Skin
- description: Change the appearance of a button with a `skin` prop. - `standard` is for general primary actions. - `light` is for primary actions that are on dark backgrounds. - `destructive` is only for actions that have a destructive effect on user data, like delete. - `premium` is for actions that prompt users to upgrade their plans to premium subscription. - `premium-light` is best for upgrade actions that appear on dark backgrounds. - `dark` should be used with buttons on backgrounds with colors. - `transparent` is for general actions on backgrounds with vivid colors or images. - `ai` should be used with AI based features.
- example:
```jsx
() => (
  <Box direction="vertical" gap="40px">
    <Box gap="20px" verticalAlign="middle">
      <Button>Standard Primary</Button>
      <Button priority="secondary">Standard Secondary</Button>
      <Button priority="tertiary">Standard Tertiary</Button>
    </Box>
    <Box gap="20px" backgroundColor="D10" padding="6px" verticalAlign="middle">
      <Button skin="light">Light Primary</Button>
      <Button skin="light" priority="secondary">
        Light Secondary
      </Button>
      <Button skin="light" priority="tertiary">
        Light Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="destructive">Destructive Primary</Button>
      <Button skin="destructive" priority="secondary">
        Destructive Secondary
      </Button>
      <Button skin="destructive" priority="tertiary">
        Destructive Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="premium">Premium Primary</Button>
      <Button skin="premium" priority="secondary">
        Premium Secondary
      </Button>
      <Button skin="premium" priority="tertiary">
        Premium Tertiary
      </Button>
    </Box>
    <Box gap="20px" backgroundColor="D10" padding="6px" verticalAlign="middle">
      <Button skin="premium-light">Premium Light Primary</Button>
      <Button skin="premium-light" priority="secondary">
        Premium Light Secondary
      </Button>
      <Button skin="premium-light" priority="tertiary">
        Premium Light Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="dark">Dark Primary</Button>
      <Button skin="dark" priority="secondary">
        Dark Secondary
      </Button>
      <Button skin="dark" priority="tertiary">
        Dark Tertiary
      </Button>
    </Box>
    <Box
      gap="20px"
      backgroundColor="#3899EB"
      padding="6px"
      verticalAlign="middle"
    >
      <Button skin="transparent">Transparent Primary</Button>
      <Button skin="transparent" priority="secondary">
        Transparent Secondary
      </Button>
      <Button skin="transparent" priority="tertiary">
        Transparent Tertiary
      </Button>
    </Box>
    <Box gap="20px" verticalAlign="middle">
      <Button skin="ai">Ai Primary</Button>
      <Button skin="ai" priority="secondary">
        Ai Secondary
      </Button>
      <Button skin="ai" priority="tertiary">
        Ai Tertiary
      </Button>
    </Box>
  </Box>
);
```

### Affix
- description: Add more context to actions with affix icons: - Emphasize the button action with a `prefixIcon`. - Indicate that an action will open a popover or navigate users to another page with a `suffixIcon`.
- example:
```jsx
<StorybookComponents.Stack flexDirection="line">
  <StorybookComponents.Stack flexDirection="column">
    <StorybookComponents.Stack>
      <Button size="large" prefixIcon={<Icons.Add />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="medium" prefixIcon={<Icons.Add />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="small" prefixIcon={<Icons.AddSmall />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="tiny" prefixIcon={<Icons.AddSmall />}>
        Prefix
      </Button>
    </StorybookComponents.Stack>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column">
    <StorybookComponents.Stack>
      <Button size="large" suffixIcon={<Icons.ChevronDown />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="medium" suffixIcon={<Icons.ChevronDown />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="small" suffixIcon={<Icons.ChevronDownSmall />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
    <StorybookComponents.Stack>
      <Button size="tiny" suffixIcon={<Icons.ChevronDownSmall />}>
        Suffix
      </Button>
    </StorybookComponents.Stack>
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

### Disabled
- description: To disable a button, use the `disabled` prop which indicates a button can't be selected.
- example:
```jsx
<Button disabled>Disabled</Button>;
```

### Text overflow
- description: Use the `ellipsis` prop for overflow text. The full text will be displayed in a `<Tooltip/>` when a user hovers over the button. Control the style of the tooltip using the `tooltipProps`. _Note_: Try to avoid lengthy action labels. CTA text should be short and clear – one to two words, or max three for specific use cases.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column" width="180px">
  <Button ellipsis>
    This label exceeds available space and is shown in a tooltip
  </Button>
</StorybookComponents.Stack>;
```

### Full width
- description: When working on mobile designs, use the `fullWidth` prop to fill the button to 100% of the parent container.
- example:
```jsx
<Button fullWidth>Full width</Button>;
```

## Developer Examples

### Custom HTML tag
- description: Render buttons as any given HTML tag with the `as` prop. For example, they can be rendered as: - `<a>` when attributes like href, target, etc., are needed. - `<Link>` when props like to, replace, etc. are needed. All attributes will be passed to the rendered HTML tag.
- example:
```jsx
() => {
  const ReactRouterLink = (props) => <div {...props} />;
  return (
    <StorybookComponents.Stack>
      <Button as="a" href="https://www.wix.com" target="_blank">
        {'Native <a/> tag'}
      </Button>
      <Button as={ReactRouterLink} skin="premium" to="/home">
        {'React Router <Link/> tag'}
      </Button>
      <Button as="button" onClick={() => alert('yay')}>
        {'Native <button/> tag'}
      </Button>
    </StorybookComponents.Stack>
  );
};
```

## Common Use Case Examples

### Loading state
- description: When an action is delayed and still loading, use [`<Loader/>`](#/component/loader) instead of a label on the button.
- example:
```jsx
<CustomModalLayout
  primaryButtonText={<Loader size="tiny" />}
  secondaryButtonText="Cancel"
  onCloseButtonClick={() => {}}
  title="Add menu"
>
  <Layout>
    <Cell>
      <FormField label="Name">
        <Input value="Brunch Menu" />
      </FormField>
    </Cell>
    <Cell>
      <FormField label="Description">
        <InputArea value="Brunch includes pastries, fruits, omelettes, coffee, and more." />
      </FormField>
    </Cell>
    <Cell>
      <Box>
        <FormField
          label="Visible to customers"
          labelPlacement="right"
          stretchContent={false}
        >
          <ToggleSwitch checked />
        </FormField>
      </Box>
    </Cell>
  </Layout>
</CustomModalLayout>;
```

### Main action of a panel
- description: Place the primary CTA button in the `<SidePanel.Footer/>` to make sure it is always clearly visible to the user.
- example:
```jsx
<SidePanel
  onCloseButtonClick={() => {}}
  skin="floating"
  width="288px"
  height="576px"
>
  <SidePanel.Header title="Manage Accordion" />
  <SidePanel.Content noPadding>
    <NestableList
      withBottomBorder
      items={[
        {
          id: 1,
          options: [{ value: <Text size="small">Color</Text> }],
          dragHandleSize: 'small',
        },
        {
          id: 2,
          options: [{ value: <Text size="small">Price</Text> }],
          dragHandleSize: 'small',
        },
        {
          id: 3,
          options: [{ value: <Text size="small">Size</Text> }],
          dragHandleSize: 'small',
        },
        {
          id: 4,
          options: [{ value: <Text size="small">Collections</Text> }],
          dragHandleSize: 'small',
        },
      ]}
      onChange={() => {}}
    />
  </SidePanel.Content>
  <SidePanel.Footer>
    <Box direction="vertical" align="center">
      <Button size="small">Add Item</Button>
    </Box>
  </SidePanel.Footer>
</SidePanel>;
```

### Priority of actions
- description: Not all actions are equal. Ranking them visually tells users what to do first, what's optional, and what's just there if they need it.
- example:
```jsx
() => (
  <Box width="460px">
    <Card>
      <Card.Header
        title="Publish Site"
        subtitle="Last edited 2 hours ago by you"
      />
      <Card.Divider />
      <Card.Content>
        <Text size="small" secondary>
          Publishing will make all changes visible to your visitors.
        </Text>
      </Card.Content>
      <Card.Divider />
      <Card.Content>
        <Box verticalAlign="middle" gap="12px">
          <Button>Publish now</Button>
          <Button priority="secondary">Save draft</Button>
          <Box marginLeft="12px">
            <Button priority="tertiary">Preview</Button>
          </Box>
        </Box>
      </Card.Content>
    </Card>
  </Box>
);
```

### Disabled state
- description: Disable the primary button when required fields are missing, and automatically enable it once all inputs are completed.
- example:
```jsx
() => {
  const [name, setName] = React.useState('');
  const [email, setEmail] = React.useState('');

  const isReady = name.trim().length > 0 && email.includes('@');

  return (
    <Box width="460px">
      <Card>
        <Card.Header
          title="Invite team member"
          subtitle="Fill in the required fields to send the invitation."
        />
        <Card.Divider />
        <Card.Content>
          <Box direction="vertical" gap="18px">
            <FormField label="Full name" required>
              <Input
                placeholder="Jane Smith"
                value={name}
                onChange={(e) => setName(e.target.value)}
              />
            </FormField>
            <FormField label="Email address" required>
              <Input
                placeholder="jane@example.com"
                value={email}
                onChange={(e) => setEmail(e.target.value)}
              />
            </FormField>
          </Box>
        </Card.Content>
        <Card.Divider />
        <Card.Content>
          <Box verticalAlign="middle" gap="12px">
            <Button disabled={!isReady}>Send invite</Button>
            <Button priority="secondary">Cancel</Button>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
};
```