# values.combine()

The `values.combine()` function combines multiple [`$values`](#usdvalues...) into the list. By default, the function use append method to combine [`$values`](#usdvalues...). The parameters of the list (`bracketed`, `delimiter`, `method`, `null`, `separator`) can be changed by providing map value eg. (method: join).

{% code lineNumbers="true" %}

```scss
// Sass.
@use 'sass:list';
@use 'sass:meta';

// Functions.
@use '../list/list.join.function' as *;

// Modules.
@use '../map';

// The `values.combine()` function.
@function combine($values...) {
  $parameters: (
    bracketed: map.get(list.nth($values, 1), bracketed, auto),
    delimiter: null,
    method: append,
    null: false,
    separator: map.get(list.nth($values, 1), separator, auto),
  );
  $result: list.join((), (), map.pick($parameters, separator, bracketed)...);
  @each $value in $values {
    $allow: true;
    $method: map.get($parameters, method);
    @if type-of($value) ==
      map and
      map.has-keys($value, any, append, join, map.keys($parameters)...)
    {
      $parameters: map.merge($parameters, map.remove($value, append, join));
      @if map.has-keys($value, any, append, join) {
        @each $use-method, $use-value in $value {
          $method: $use-method;
          $value: $use-value;
        }
      } @else {
        $allow: false;
      }
    }
    @if not map.get($parameters, null) and not $value {
      $allow: false;
    }
    @if $allow {
      $result: meta.call(
        meta.get-function($method),
        $result,
        $value,
        map.pick(
            $parameters,
            if($method == join, (separator, bracketed), separator)...
          )...
      );
    }
  }
  @if map.get($parameters, delimiter) {
    $result: join((), $result, map.pick($parameters, separator, delimiter)...);
  }
  @return $result;
}
```

{% endcode %}

{% embed url="<https://github.com/angular-package/sass/blob/main/values/_values.combine.function.scss>" %}

### Parameters

#### **`$values...`**

Arbitrary values to combine into the returned list.

### Return

The return value is the `list` combined by the specified method, with a separator, and/or delimiter.

## Examples

```scss
// Use.
@use '@angular-package/sass/values';

// Examples.
// The default append method + separator auto.
@debug values.combine('&', layout sidebar, primary dark, extra small); // "&" (layout sidebar) (primary dark) (extra small)
@debug values.combine(('&', dark), layout sidebar, primary dark, extra small); // ("&", dark) (layout sidebar) (primary dark) (extra small)

// Join method + separator auto.
@debug values.combine((method: join), '&', layout sidebar, primary dark, extra small); // "&" layout sidebar primary dark extra small
@debug values.combine((method: join), ('&', dark), layout sidebar, primary dark, extra small); // "&", dark, layout, sidebar, primary, dark, extra, small
@debug values.combine((method: join), '&' dark, layout sidebar, primary dark, extra small); // "&" dark layout sidebar primary dark extra small

// Append method + separator space and comma.
@debug values.combine((separator: space), '&', layout sidebar, primary dark, extra small); // "&" (layout sidebar) (primary dark) (extra small)
@debug values.combine((separator: comma), '&', layout sidebar, primary dark, extra small); // "&", layout sidebar, primary dark, extra small

// Join method + separator space and comma.
@debug values.combine((separator: space, method: join), '&', layout sidebar, primary dark, extra small); // "&" layout sidebar primary dark extra small
@debug values.combine((separator: comma, method: join), '&', layout sidebar, primary dark, extra small); //  "&", layout, sidebar, primary, dark, extra, small

// Combine with `append` or `join` key.
@debug values.combine((append: first append), '&', layout sidebar, primary dark, extra small); // (first append) "&" (layout sidebar) (primary dark) (extra small)
@debug values.combine((append: (first, append)), '&', layout sidebar, primary dark, extra small); // (first, append) "&" (layout sidebar) (primary dark) (extra small)

@debug values.combine((join: first append), '&', layout sidebar, primary dark, extra small); // first append "&" layout sidebar primary dark extra small
@debug values.combine((join: (first, append)), '&', layout sidebar, primary dark, extra small); // first, append, "&", layout, sidebar, primary, dark, extra, small

@debug values.combine((method: join), '&', layout sidebar, (append: first append), primary dark, extra small); // "&" layout sidebar (first append) primary dark extra small
@debug values.combine('&', layout sidebar, (join: first join), primary dark, extra small); // "&" (layout sidebar) first join (primary dark) (extra small)

@debug values.combine((method: join, separator: comma), '&', layout sidebar, (append: first append), primary dark, extra small); // "&", layout, sidebar, first append, primary, dark, extra, small
@debug values.combine((separator: comma), '&', layout sidebar, (join: first join), primary dark, extra small); // "&", layout sidebar, first, join, primary dark, extra small

// Bracketed.
@debug values.combine((bracketed: true), '&', layout sidebar, primary dark, extra small); // ["&" (layout sidebar) (primary dark) (extra small)]

// Bracketed + separator.
@debug values.combine((bracketed: true, separator: comma), '&', layout sidebar, primary dark, extra small); // ["&", layout sidebar, primary dark, extra small]

// Bracketed + join method.
@debug values.combine((bracketed: true, method: join), '&', layout sidebar, primary dark, extra small); // ["&" layout sidebar primary dark extra small]

// Bracketed + separator + join method
@debug values.combine((method: join, separator: comma, bracketed: true), '&', layout sidebar, primary dark, extra small); // ["&", layout, sidebar, primary, dark, extra, small]

// Change method.
@debug values.combine((one, two), three, (four, five), (six seven), primary dark, extra small); // (one, two) three (four, five) (six seven) (primary dark) (extra small)
@debug values.combine((one, two), three, (method: join), (four, five), (six seven), primary dark, extra small); // (one, two) three four five six seven primary dark extra small
@debug values.combine((one, two), three, (method: join), (four, five), (six seven), (method: append), primary dark, extra small); // (one, two) three four five six seven (primary dark) (extra small)

// method (join: value) (append: value)
@debug values.combine((join: (one, two)), (join: three), (four, five), (six seven), primary dark, extra small); // one two three (four, five) (six seven) (primary dark) (extra small)
@debug values.combine((join: one two), three, (four, five), (six seven), (append: (primary dark extra small))); // one two three (four, five) (six seven) (primary dark extra small)

// Add delimiter + add null values.
@debug values.combine(['a' 1], 'b' 2, ['c' 3], null, (separator: comma, null: true, delimiter: '-'), null, null, (append: 1 2 3), age 32, first name ); // ["a" 1], "-", "b" 2, "-", ["c" 3], "-", null, "-", null, "-", 1 2 3, "-", age 32, "-", first name
@debug values.combine((method: join, delimiter: separator), 'a' 1 , 'b' 2, 'c' 3); // "a" separator 1 separator "b" separator 2 separator "c" separator 3
@debug values.combine((method: join, separator: comma, delimiter: separator basic), 'a' 1 , 'b' 2, 'c' 3); // "a", separator basic, 1, separator basic, "b", separator basic, 2, separator basic, "c", separator basic, 3
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.angular-package.dev/sass/values/values.combine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.