freesewing/sites/dev/docs/reference/macros/sa/readme.mdx

---
title: sa
---

The `sa` macro will create seam allowance paths.

Unlike the core [`Path.join()`](/reference/api/path/join) and
[`Path.offset()`](/reference/api/path/offset) functions, the
`sa` macro can extend line ends to meet in a sharp corner and
will automatically trim useless path ends when adjacent paths
in the array are intersecting.

:::note
##### Not a core-plugins macro

The `sa` macro is not provided by the [core plugins](/reference/plugins/core),
so you need to load the [path-utils plugin](/reference/plugins/path-utils)
explicitly if you want to use it.
:::

## Signature

```js
macro('sa', {
  Array paths,
  number limit,
  string mode,
  string class
})
```

## Example

<Example caption="An example of the sa macro">

```js
({ Point, points, Path, paths, macro, part }) => {
  paths.outline = new Path()
    .move(new Point(10, 30))
    .line(new Point(30, 30))
    .line(new Point(30, 50))
    .line(new Point(50, 50))
    .line(new Point(50, 70))
    .line(new Point(70, 70))
    .curve(new Point(55, 15), new Point(55, 15), new Point(30, 0))

  paths.outline2 = new Path().move(new Point(30, 0)).line(new Point(10, 30))

  paths.sa = macro('sa', {
    paths: ['outline', { p: 'outline2', offset: 30 }],
    sa: 10,
  }).setClass('stroke-sm mark dotted')

  paths.halfCircle = new Path().move(new Point(100, 0)).circleSegment(37, new Point(200, 0)).hide()

  paths.halfCircleClosed = paths.halfCircle.clone().line(new Point(200, 0)).unhide().close()

  paths.halfCircleSa = macro('sa', {
    paths: ['halfCircle', null],
    sa: 10,
  }).setClass('stroke-sm mark dotted')

  return part
}
```

</Example>

## Configuration

| Property | Default          | Type     | Description                                                                                                                                                                                                                                                 |
| -------: | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  `paths` |                  | `array`  | An array of paths. You can use path names in the `paths` array or reference `Path` objects directly, or insert `null` elements to create gaps. You can also override offset and visibility for individual paths in the same way as with the `offset` macro. |
|   `mode` | `'corner'`       | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly (like `Path.join()`) without extending the corners.                                                                                                           |
|  `limit` | `null`           | `number` | Allows limiting the length of extended path corners in `'corner'` mode. Prevents overly long joins on very sharp angles. Ignored if `null` or `false`.                                                                                                      |
|     `sa` | (seam allowance) | `number` | Allows you to override the seam allowance used for this macro. Defaults to the standard seam allowance (`sa` parameter in draft function).                                                                                                                  |
|  `class` | `'sa'`           | `string` | CSS class that is automatically applied to the resulting path.                                                                                                                                                                                              |

## Notes

The `sa` macro accepts an array of `Path` objects
(either names in the `paths` array or direct references to `Path` objects).
This array can contain `null` values to create gaps (e.g. for cuts on the fold or for other sections that don't need seam allowance).

By default, the `sa` macro will sa the paths in a circular fashion, joining the end
of the last path in the array to the start of the first path, creating a full outline.
If this is not desired, insert `null` elements where you want to create gaps.

You can optionally override the offset and invisibility for individual paths.
To do so, insert an object literal like `{p: 'somePath', offset: 30}` or `{p: ['path1', 'path2'], offset: sa * 3, hidden: true}` into the `paths` array.

You can use `offset: 0` to include paths which have already build-in the seam allowance (e.g. the result of the `hem` macro).

You can use `hidden: true` to hide path segments from the output, but still build corner joins as if they were there.
This can be used for cut-on-fold lines, where no seam allowance is needed.